CLAUDE.md · git:20261011.3352d02 · 2026-10-11 · sha256 a90c87e9738b1af8

CLAUDE.md git:20261011.3352d02A

Immutable. This exact content never changes and is served at /api/v1/blob/a90c87e9738b1af8.

# CLAUDE.md: working in better-agentic-ide

This file is the project **constitution**: the standing decisions and conventions every
agent follows, so parallel and later work stays consistent. It is loaded into every
Claude Code session; read it first and don't contradict it.

This is an **ADE** project: disciplined AI development, *verified, not vibed*. Work flows
**Plan → Approve → Shard → Build → Verify**, and **a story is Done only when the agreed
verification command passes**. No agent certifies its own work.

@.ade/rules.md

## If you are a Developer agent working a story
- Implement ONLY the assigned story. Work **test-first**: write the failing test, then
the minimal code to make it pass.
- Follow the coding standards below and the story's acceptance criteria exactly.
- **Do NOT mark the story Done or self-report success.** Run the verification command,
report its real output, and stop. QA or the owner decides.

## Agents and commands
- **Sub-agents** in `.claude/agents/`: product-manager, architect, designer, scrum-master,
developer, qa, devops, adversarial-reviewer. Delegate to the one that owns the work.
- **BMAD** tasks, checklists, templates and workflows, in the version `.ade/methodology`
names. **v4**: the `/BMad:tasks:` slash commands in `.bmad-core/`. **v6**: the skills
in `.claude/skills/`, with work in `_bmad-output/`. Either way these are optional
helpers you may run inside the flow. BMAD's own
personas are deliberately not installed — eight of them are the same jobs as the
sub-agents above, and two definitions of Done is worse than one. The ADE rules in `.ade/rules.md` always
win: a BMAD task can **never override** the verification command, the Definition of
Done, or anything in this file. Where they disagree, stop and surface the conflict.
- `adversarial-reviewer` ships with a read-only tool allowlist on purpose: it
judges, it does not patch. Don't widen it to "unblock" a story. `qa` can write, but
only the story's Verification section and the journal — never the code or tests it judges.

## Project layout
- `docs/prd.md`: product requirements (the product-manager owns this).
- `docs/architecture.md`: system design and, under "Verification command", the single
command that decides Done (the architect owns this).
- `docs/ux-spec.md`, `docs/mockup.html`: design artifacts (the designer).
- `docs/ops.md`: CI/CD, environments, rollout, rollback, monitoring (devops).
- `docs/stories/`: one file per story, the unit of work (the scrum-master).
- `.ade/rules.md`: **the rules**: the methodology and the non-negotiables.
- `.ade/context/`: the **Context Store**: shared interfaces, types and decisions that
parallel and later stories must agree on. Read it before inventing a contract.
- `.ade/context/decisions/`: the **decision log** (ADRs: `NNNN-slug.md`).
- `.ade/session.md`: the **session journal**: what's been planned, built and shipped.

## The journal
Append one dated line to `.ade/session.md` at each milestone, so the next session can see
what happened: the **architect** records an approved plan, the **scrum-master** records
each story sharded, and **QA** records a story Done once the verification command passes.

## Discipline
- Small, vertically sliced, independently testable changes.
- Tests are the contract. If the verification command fails, the work is not done.
- No scope creep, no gold-plating.

## Coding standards and conventions (the constitution)