Skip to main content
Experimental version.This is the latest in-development version of AI-Implement. Features may change without notice and behavior is not guaranteed. Switch to the latest stable version here.
PLANNING.md controls what Claude does during the planning phase — it reads the codebase and posts structured architecture analysis, test plan, work units, and cross-story comments back to your ticketing system. When the planning workflow (claude-plan.yml) runs for an issue, it renders this file and sends the result to Claude. Claude then explores the repo and writes structured planning comments back to the issue — without creating any branches, files, or pull requests.

​
File structure

Like WORKFLOW.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. Processed with envsubst and sent to Claude as the prompt.

​
Front matter keys

The model ID passed to claude-code --model. Accepts any ID your configured provider supports.
# Anthropic API or OAuth
model: claude-sonnet-4-6

# AWS Bedrock (replace with your model ID or inference-profile ARN)
model: anthropic.claude-sonnet-4-6-20250805-v1:0
This key is required when using Bedrock — there is no safe default for Bedrock model IDs. The workflow hard-fails if you omit it on a Bedrock-mapped repo. For the Anthropic provider it defaults to claude-sonnet-4-6 if omitted.

​
Variables available in the body

The markdown body is processed with envsubst before being sent to Claude. You can reference any of these variables anywhere in the body:
VariableDescription
${ISSUE_IDENTIFIER}Ticketing-system identifier — ENG-42 for Linear, PROJ-42 for Jira
${ISSUE_TITLE}Issue title
${ISSUE_DESCRIPTION}Full issue description (Markdown)
${ISSUE_ID}Issue UUID — used in API calls to post comments
${PARENT}Parent issue as - IDENTIFIER: Title, or None
${SIBLINGS}Sibling stories (other children of the same parent), newline-separated, or None
${DEPENDENCIES}Related issues as - [type] IDENTIFIER: Title, newline-separated, or None

​
Comment types Claude must post

Claude posts up to four structured comments to your ticketing issue. The headers are exact strings the implementation workflow uses to locate planning context later, so do not change them.
1

Architecture Analysis

Header: ## 🏗️ AI Planning: Architecture AnalysisRequired sections in this comment:
  • Approach — 1–3 sentences describing the implementation strategy
  • Files to Create/Modify — specific file paths with a one-line description of each change
  • Key Decisions — architectural choices and rationale
  • Risks & Open Questions — edge cases, unknowns, potential problems
2

Test Plan

Header: ## 🧪 AI Planning: Test PlanRequired sections in this comment:
  • Unit Tests — individual components or functions to test
  • Integration Tests — end-to-end or cross-component scenarios
  • Manual Verification — step-by-step human verification checklist
3

Work Units

Header: ## 🔧 AI Planning: Work UnitsDecompose the issue into work units that subagents can implement in parallel during the implementation phase.Required sections in this comment:
  • Independent (can be implemented in parallel) — units with no dependencies on other units.
  • Sequential (must follow independent units) — units that depend on the independent ones completing first.
Each unit must specify a name, description, files touched, and dependencies (or No dependencies), formatted as follows:
- **WU-1: Add the user-export endpoint** — Files: `src/api/export.ts`. No dependencies.
- **WU-2: Update the schema migration** — Files: `migrations/0042-export.sql`. No dependencies.
- **WU-3: Update the frontend to reflect new schema** — Files: `src/app/export/page.tsx`. Depends on: WU-2.
Claude may omit this comment when the issue doesn’t naturally decompose — for example, when all the work is sequential or tightly coupled across files. Implementation falls back to a single-pass run in that case.
4

Cross-Story Context (conditional)

Header: ## 🔗 AI Planning: Cross-Story ContextClaude only posts this comment when ${DEPENDENCIES} or ${SIBLINGS} is not None and there is meaningful coordination needed between stories.Required sections when posted:
  • Upstream Dependencies — what must be completed before this story
  • Downstream Impact — stories or systems that will depend on this work
  • Coordination Notes — specific actions needed to coordinate with other teams or stories

​
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. 
## Repo context

- **Stack:** Node.js 20, TypeScript 5, PostgreSQL 16, Prisma ORM, Vitest
- **Key conventions:**
  - All database access goes through the repository layer in `src/repositories/`
  - API routes live in `src/api/routes/`; middleware in `src/api/middleware/`
  - Avoid introducing new dependencies without good reason
- **Areas to always check:** `src/models/`, `src/api/`, `migrations/`
Use the Areas to always check field to direct Claude to the directories most likely to be relevant for any given issue. This reduces analysis time and keeps the architecture comments grounded in your actual code structure rather than generic advice.

​
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: 
## Repo context

- **Areas to always check:** `src/models/`, `src/api/`, `migrations/`
- If the issue involves data changes, check `migrations/` for the latest schema
  and assess whether a new migration is needed.
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.