CLAUDE.md

1# CLAUDE.md
2 
3## Purpose
4 
5This file defines how Claude Code should work on the Conditions Translator project.
6 
7Keep this file concise. Detailed product and architecture rules live in the project documentation.
8 
9---
10 
11# 1. Non-Negotiable Rules
12 
13Claude must:
14 
15- Read the project documentation before implementation.
16- Ask for clarification whenever the task, requirements, or next step is unclear.
17- Preserve the approved architecture unless an explicit architecture-change process is followed.
18- Never change the PRD.
19- Never bypass the `READY` document requirement.
20- Never bypass ownership or authorization checks.
21- Never expose server secrets.
22- Never push or merge Git branches.
23- Make all local commits.
24- Use PowerShell commands only.
25- Update `.gitignore` when new local, generated, temporary, or secret files are introduced.
26- Keep commits small, logical, and descriptive.
27- Check current official documentation before installing or configuring dependencies whose setup may have changed.
28 
29---
30 
31# 2. Required Reading Order
32 
33Before coding:
34 
351. `README.md`
362. `docs/01_MVP_PRD.md`
373. `docs/02_Architecture_Overview.md`
384. Relevant subsystem specification
395. `docs/08_Conditions_Translator_Implementation_Roadmap.md`
406. Relevant risk and launch-readiness sections
41 
42Do not start implementation until the applicable specification has been reviewed.
43 
44---
45 
46# 3. Git Workflow
47 
48## Branches
49 
50Create a dedicated branch for each:
51 
52- phase
53- feature
54- test effort
55- bug fix
56- refactor
57- rework
58- documentation change
59- chore
60 
61Use these prefixes:
62 
63```text
64feat/
65fix/
66refactor/
67test/
68docs/
69chore/
70rework/
71build/
72ci/
73```
74 
75Examples:
76 
77```text
78feat/document-intake
79test/prisma-ownership
80fix/chat-session-expiry
81refactor/ocr-service
82docs/update-schema-spec
83chore/configure-eslint
84rework/account-transfer
85```
86 
87Claude may create branches and make local commits.
88 
89Claude must not:
90 
91- push branches
92- merge branches
93- open or merge pull requests without explicit instruction
94 
95The user will push and merge through GitHub.
96 
97## Staging Discipline
98 
99- Stage files individually by name (`git add <file> <file> ...`). Never use `git add -A` or `git add .`.
100- Only stage files that are actually in scope for the current task.
101- After each commit, report which touched files were included and which untracked/modified files were deliberately left out, so leftover changes in the working tree are never mistaken for a staging failure.
102 
103---
104 
105# 4. Commit Rules
106 
107Use small, coherent commits.
108 
109Do not commit an entire phase or large feature as one oversized commit.
110 
111Use conventional prefixes:
112 
113```text
114feat:
115fix:
116refactor:
117test:
118docs:
119chore:
120build:
121ci:
122perf:
123style:
124revert:
125```
126 
127Examples:
128 
129```text
130feat: add temporary document creation flow
131test: cover exclusive document ownership constraints
132fix: prevent expired sessions from loading documents
133refactor: separate OCR validation from provider client
134docs: update account ownership specification
135chore: ignore generated local files
136```
137 
138Commit messages must be:
139 
140- descriptive
141- concise
142- understandable to another developer or employer
143- focused on one coherent change
144 
145A phase may contain many commits.
146 
147---
148 
149# 5. PowerShell-Only Commands
150 
151All commands must be written for PowerShell.
152 
153Do not provide Bash syntax unless explicitly requested.
154 
155Use PowerShell for:
156 
157- package installation
158- file creation
159- directory creation
160- environment setup
161- testing
162- database commands
163- Git commands
164- local development
165- build commands
166- cleanup
167 
168Examples:
169 
170```powershell
171npm install
172npm run dev
173npm run build
174npm run test
175npx prisma generate
176npx prisma migrate dev
177Copy-Item .env.example .env.local
178New-Item -ItemType Directory -Path .claude\session-memory -Force
179```
180 
181---
182 
183# 6. Dependency and Documentation Checks
184 
185Before installing or configuring important dependencies:
186 
1871. Read the relevant project specification.
1882. Check current official documentation.
1893. Confirm the integration pattern is current.
1904. Explain any setup choice that differs from older examples.
1915. Avoid relying on outdated syntax.
192 
193This is especially important for:
194 
195- Prisma
196- Next.js
197- authentication libraries
198- OpenAI SDK
199- Vercel Blob
200- Neon
201- testing frameworks
202- build tooling
203 
204Do not install a dependency based only on memory when current setup details may have changed.
205 
206---
207 
208# 7. Architecture Boundaries
209 
210Claude must preserve these invariants:
211 
212- A Document is the central domain object.
213- Pages belong to exactly one Document.
214- A Document has exactly one owner:
215  - user
216  - or temporary session
217- Only `READY` Documents are available to AI.
218- Accepted page text is the factual source of truth.
219- AI chat is temporary.
220- Full chat history is not permanent.
221- AI answers are grounded in selected READY Documents.
222- General AI knowledge must not fill supervision gaps.
223- Architecture changes require a separate Decision Log entry and explicit approval.
224 
225---
226 
227# 8. Package Scripts
228 
229Keep `package.json` scripts clear and easy to inspect.
230 
231Add scripts incrementally as functionality is implemented.
232 
233Suggested structure:
234 
235```json
236{
237  "scripts": {
238    "dev": "next dev",
239    "build": "next build",
240    "lint": "eslint .",
241    "typecheck": "tsc --noEmit",
242    "test": "vitest run",
243    "test:watch": "vitest",
244    "test:schema": "vitest run tests/schema",
245    "test:auth": "vitest run tests/auth",
246    "db:generate": "prisma generate",
247    "db:migrate": "prisma migrate dev",
248    "db:validate": "prisma validate"
249  }
250}
251```
252 
253Do not add scripts that duplicate existing behavior without a clear reason.
254 
255---
256 
257# 9. Testing Expectations
258 
259Required for:
260 
261- schema and ORM changes
262- authentication
263- authorization and ownership
264- document lifecycle
265- deletion and cleanup
266- security-sensitive code
267- environment configuration
268- temporary sessions
269 
270Strongly advised for:
271 
272- OCR
273- AI prompts
274- safety behavior
275- section generation
276- uploads
277- dashboard
278- multi-document chat
279 
280Optional for:
281 
282- documentation-only changes
283- styling-only changes
284- copy changes
285- non-functional refactors
286 
287Always report:
288 
289- tests run
290- tests passed
291- tests failed
292- tests not run
293- known gaps
294 
295---
296 
297# 10. UI Rules
298 
299Current UI guidance is intentionally limited.
300 
301- Mobile-first.
302- Must also work in desktop browsers.
303- Prioritize functional flows before polish.
304- Prefer one primary decision per screen where practical.
305- Use clear loading, empty, success, and error states.
306- Do not invent final styling or interaction patterns before wireframes exist.
307- Add basic wireframes when a flow needs validation.
308- Preserve readability, accessibility, and simple navigation.
309- Avoid overbuilding the visual system before core logic is stable.
310 
311---
312 
313# 11. Clarification Rule
314 
315If Claude is unsure:
316 
317- stop
318- explain what is unclear
319- ask a focused clarification question
320- do not guess at architecture
321- do not invent requirements
322- do not proceed silently
323 
324This applies to:
325 
326- unclear requirements
327- conflicting documents
328- uncertain implementation direction
329- missing dependencies
330- ambiguous acceptance criteria
331- unclear test expectations
332 
333---
334 
335# 12. Local Session Memory
336 
337## Session continuity and working memory
338 
339Before starting or continuing any non-trivial task, Claude should review available local session-memory files (if present) and update them when useful.
340 
341Use session memory to:
342- capture the task being worked on
343- record important context, assumptions, and constraints
344- note open questions, risks, or follow-up items
345- preserve handoff context if the session may be interrupted or hit context limits
346 
347Guidelines:
348- Keep memory notes short, factual, and useful for future continuation
349- Update memory before or during meaningful work when the task involves debugging,
350  behavior changes, architecture decisions, environment/configuration changes,
351  multi-file edits, or unresolved questions
352- Prefer updating local gitignored memory files rather than creating extra repo docs
353  unless the information belongs in project documentation
354- Do not commit local session-memory files unless explicitly told to do so
355 
356Use local memory files for long sessions and context handoff.
357 
358Repository location:
359 
360```text
361.claude/
362  session-memory/
363    CURRENT_SESSION.md
364    DECISIONS.md
365    OPEN_QUESTIONS.md
366    WORK_LOG.md
367```
368 
369Required behavior:
370 
371- Read these files before resuming work in a new session.
372- Update `CURRENT_SESSION.md` during long sessions.
373- Record durable decisions in `DECISIONS.md`.
374- Record unresolved issues in `OPEN_QUESTIONS.md`.
375- Add concise chronological notes to `WORK_LOG.md`.
376- Never store secrets, tokens, passwords, private document text, or sensitive user data.
377- Keep entries concise.
378- Update `.gitignore` based on whether each file should remain local or be committed.
379 
380Recommended policy:
381 
382Local only:
383- `CURRENT_SESSION.md`
384- `WORK_LOG.md`
385 
386May be committed when project-relevant:
387- `DECISIONS.md`
388- `OPEN_QUESTIONS.md`
389 
390---
391 
392# 13. AI Change Summary
393 
394For meaningful changes, report:
395 
3961. What changed?
3972. Why was it changed?
3983. Which specification guided the work?
3994. What assumptions were made?
4005. What tests were run?
4016. What remains untested?
4027. What should happen next?
403 
404---
405 
406# 14. Stop Conditions
407 
408Stop and ask before:
409 
410- changing architecture
411- changing the PRD
412- changing ownership behavior
413- changing document lifecycle states
414- changing AI grounding rules
415- replacing a major framework or provider
416- introducing permanent chat storage
417- weakening authorization
418- changing data-retention behavior
419- installing a major dependency without checking current official documentation
420