Skip to content

fix(subagent-prompts): instruct subagents to read CLAUDE.md for project conventions#899

Open
arittr wants to merge 1 commit intodevfrom
drew/subagent-read-claude-md
Open

fix(subagent-prompts): instruct subagents to read CLAUDE.md for project conventions#899
arittr wants to merge 1 commit intodevfrom
drew/subagent-read-claude-md

Conversation

@arittr
Copy link
Collaborator

@arittr arittr commented Mar 23, 2026

Summary

  • Adds a one-liner to each of the three subagent dispatch templates instructing subagents to read CLAUDE.md (or AGENTS.md) before starting work
  • implementer-prompt.md: "Read CLAUDE.md... its conventions are binding on your work" in the Before You Begin section
  • spec-reviewer-prompt.md: "verify the implementation follows its conventions" in the Your Job section
  • code-quality-reviewer-prompt.md: "use its conventions as review criteria" before the review checklist

Why

Subagents spawned via the Agent tool start with a fresh context — no CLAUDE.md pre-loaded. They pattern-match existing code well, but miss cross-cutting conventions only documented in CLAUDE.md (test location, DB mocking policy, architectural boundaries, error format conventions).

RED/GREEN tested across multiple scenarios including legacy codebases with conflicting patterns. Without the fix, subagents copy legacy anti-patterns (if/else, try/catch, console.log, argument mutation). With the fix, subagents read CLAUDE.md first and follow its conventions over conflicting existing code.

Test plan

  • RED tested: subagents without fix copy legacy patterns from existing code
  • GREEN tested: subagents with fix read CLAUDE.md and follow its conventions over conflicting code
  • Verified fix works with empty projects (CLAUDE.md only, no existing code)
  • Verified fix works with conflicting legacy code (no disclaimer comments)
  • Manual verification in a real SDD workflow

Closes #793
Related: #804

🤖 Generated with Claude Code

@arittr arittr changed the base branch from dev to drew/codex-named-agent-dispatch March 24, 2026 00:06
@arittr arittr force-pushed the drew/fix-frontmatter-docs branch from 1830941 to c141508 Compare March 24, 2026 01:43
@arittr arittr force-pushed the drew/subagent-read-claude-md branch from 457abac to 0cc80b1 Compare March 24, 2026 01:43
@arittr arittr changed the base branch from drew/fix-frontmatter-docs to dev March 24, 2026 01:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Subagent prompts should include explicit instructions to read CLAUDE.md Why use Claude Code's general-purpose agent in subagent-driven development?

1 participant