PLANNING.md controls what Claude does during the planning phase. When the planning workflow (claude-plan.yml) runs for an issue, it renders this file and sends the result to Claude as the prompt.
Claude explores the repo read-only and writes planning comments back to the issue, without creating any branches, files, or pull requests.
File structure
LikeWORKFLOW.md, PLANNING.md has two parts:
YAML front matter (between the --- lines at the top) — read by the workflow to configure the run. Stripped before Claude sees anything.
Markdown body — everything after the front matter. A fixed list of variables is substituted into it, and the result is sent to Claude as the prompt.
Front matter keys
model
model
The model ID passed to This key is required when using Bedrock. There is no Bedrock-specific default — the model resolves from a single provider-agnostic chain that ends in
claude-code --model. Accepts any ID your configured provider supports.claude-sonnet-4-6.Omit it on a Bedrock-mapped repo and that Anthropic model ID is substituted silently. It is invalid on Bedrock, so the run fails when the model is invoked rather than up front.For the Anthropic provider, claude-sonnet-4-6 is the intended default and omitting the key is safe.Variables available in the body
The variables below are substituted into the body by a regular expression, not byenvsubst. Reference any of them anywhere in the body.
Only
${NAME} forms are substituted, and a token that is not on this list is treated differently than shell semantics would suggest. Workflow template files covers the rules and what they mean for a shell example in your body.Comment types Claude must post
Claude writes every one of the following as its own comment on your ticketing issue. The headers are exact strings the implementation workflow uses to locate planning context later, so do not change them.Implementation Map
Header:## 🗺 AI Planning: Implementation Map
Written for whoever implements the issue, and capped at 60 lines.
Required sections in this comment:
- Approach — at most three sentences describing the implementation strategy
- Files — one bullet per file, each opening with
Create:,Modify:,Test:orDelete:followed by a backtick-quoted path - Constraints & Hazards — load-bearing tests, generated files, migration ordering, and integration seams the implementer must not break
${DEPENDENCIES}, ${SIBLINGS} or ${PARENT} is not None, rather than in a comment of its own.
The comment ends with a machine-readable block:
Acceptance Bar
Header:## ✅ AI Planning: Acceptance Bar
Written for the reviewer, and handed to the review pass so it has something falsifiable to check the diff against.
A numbered list of claims, each one checkable against the diff or by running a named command. A generic enumeration doesn’t qualify — “all tests pass” is not a claim.
Risks & Open Questions
Header:## ⚠️ AI Planning: Risks & Open Questions
Written for the implementer and the reviewer both.
Edge cases, unknowns, and problems found while exploring the codebase, grounded in what Claude actually found rather than generic boilerplate.
Customizing the “Repo context” section
The## Repo context section is where you point Claude at the right parts of your codebase and establish the conventions that matter for architectural decisions.
Example: adding analysis prompts
You can add repo-specific analysis instructions anywhere in the body. For example, to always have Claude check the migration directory when database changes are involved:The sync workflow seeds
PLANNING.md into your repo once and never overwrites it. Every change you make is permanent — future syncs will not touch this file.