Context Management

menu_bookGuideline

AI without context invents APIs, reinvents existing patterns, and contradicts prior decisions.

Rule

The AI must read the required context (CLAUDE.md, plans, ADRs, affected code) before modifying anything, and must keep context artifacts up to date when things change.

Why

AI without context invents APIs, reinvents existing patterns, and contradicts prior decisions. The context hierarchy grounds the AI in the project's current reality.

How

For every task, read at minimum the project's CLAUDE.md. Add plans/specs for feature work, ADRs and architecture docs for architecture changes, existing code for code changes, and a preview of current state for visual/physical output. Never skip context to save time.

Context Hierarchy

CLAUDE.md (project root)
├── context/architecture/  — Architecture overview
├── context/adr/           — Decisions made
├── context/guidelines/    — Development guidelines
├── context/plans/         — Active and completed plans
└── context/specs/         — Feature specifications

What AI MUST Read

Situation	Minimum Context
Any work	CLAUDE.md
Feature work	+ relevant plan/spec
Architecture change	+ ADRs + architecture docs
Code change	+ existing affected code
Visual / physical output	+ preview of current state

Shared vs. Branch-Local Artifacts

Category	Artifacts	Rules
Shared (main)	CLAUDE.md, System Spec, Architecture	Read-only during feature work. Modified only via PR after merge. Never edited in parallel.
Branch-local	Plans (CTX/EXP/PRD), Feature Specs, ADRs	Created on the agent's branch. Merged via PR. Conflicts resolved by human.

menu_book guidelines/context-management.mdopen_in_new