What Claude Decides On Its Own

Claude makes hundreds of decisions during a build. It sorts each one by how much you’d want to know about it, from routine choices it makes silently to the few it always stops and asks you about.

The four levels

Level	What Claude does	Where the decision is recorded
1. Decide and proceed	Makes the call and moves on	A note in the story’s commit message
2. Decide and journal	Makes the call and writes a plain-language note	The epic’s journal
3. Decide and flag	Makes the call and records it for whoever needs to check it	The “Check these first” list at your manual test, or the architecture registry
4. Stop and ask	Pauses the build until you decide	A question in the chat, with options and a recommendation

Routine decisions

Level 1 covers standard choices that are low-risk and easy to reverse:

• Naming and structure: file names, folder layout and code organisation
• Test patterns: how tests are written and what test data they use
• Component choice: which shadcn component fits, when more than one would work
• UI defaults: default sort order, page size, and empty-state and loading text
• Accessibility basics: labels on icon buttons and focus handling in dialogs
• Error handling: retry buttons and standard error messages

Level 2 covers choices you’d want to know about afterwards. Examples include sharing a component rather than repeating it, or validating a form on submit rather than as you type. A field the brief didn’t mention but the build turned out to need is also level 2. Claude updates the epic’s brief where needed and notes the change in the journal.

Decisions Claude flags for you to confirm

Some decisions depend on things Claude can’t check: the exact shape of a response from your real backend, a URL, a brand colour, or how to read an ambiguous requirement. Claude makes the most reasonable assumption, keeps building, and adds the assumption to a “Check these first” list.

That list appears at the top of your manual test checklist, before the epic merges. Automated tests can’t catch a wrong assumption of this kind, because the mock data makes the same assumption as the code. If an item turns out to be wrong, tell Claude the real answer. It corrects the API spec, the mock data and the tests before it fixes the code.

Level 3 also covers shared components and conventions that later epics should reuse. Claude records these in generated-docs/architecture.md, so each new epic builds on what already exists.

Decisions Claude always asks you about

Claude stops the build and asks you before it:

• Changes who can do what in the app
• Changes the shape of an API request or response
• Calls an endpoint, parameter or header that your OpenAPI spec doesn’t document
• Adds a new npm package or third-party service
• Changes how sign-in or sessions work
• Changes the app’s overall structure, such as its routing or page layout shell
• Does something that contradicts your approved brief or a project rule

Each question explains what Claude was doing, why it stopped, and the options, with a recommendation. The build carries on as soon as you answer.

Decisions that are always yours

• The scope: the project setup, the epic plan and each epic’s stories
• The result: whether each epic works, which you decide at the manual test
• The merge: when an epic goes into main
• Git approvals: whether Claude commits and pushes without asking, which you choose the first time you run /start

Where to look later

Each epic’s journal, at generated-docs/epics/<slug>/journal.md, is a plain-language record of the decisions Claude made while building it. If something was built in a way you didn’t expect, start there. See What the Workflow Produces for the other files.