Use case
We use Claude Code on this repo for issue triage and PR reviews (the claude.yml and claude-code-review.yml workflows are already wired up). Each session currently has to re-discover basic context — that this is a dual-language monorepo with parallel Python and TypeScript implementations, where the build/lint/test commands live, the orchestrator/classifier/agent/storage/retriever architecture, and the CI-enforced issue-first PR policy.
Without a CLAUDE.md at the repo root, every run wastes tokens and time re-learning the same facts, and is more likely to miss conventions (e.g. opening a PR without a linked issue, or making a change in one language tree but not the parallel file in the other).
Solution / User experience
Add a root-level CLAUDE.md that captures:
- Repo shape — the
python/ + typescript/ feature-parity expectation and the rename history (multi-agent-orchestrator → agent-squad, awslabs → 2fastlabs).
- Common commands for both trees (
make code-quality, make test, npm run lint, npm run coverage, single-test invocations, the prebuild version-file quirk).
- High-level architecture:
AgentSquad orchestrator, Classifier, Agent hierarchy, ChatStorage, Retriever, plus the composite ChainAgent / SupervisorAgent patterns.
- CI-enforced rules that affect PR authoring: issue-first policy, PR template, Python 3.11–3.13 matrix, Lychee link check.
- Cross-implementation notes: snake_case vs camelCase exports,
*Options dataclass pattern, try/except ImportError gating for optional extras.
After: Claude Code sessions load this context automatically and produce higher-quality, convention-aware PRs and issue responses on the first pass.
Alternative solutions
- Rely on the README alone — rejected because the README is user-facing marketing/getting-started content, not a contributor/agent runbook.
- Put the guidance in
CONTRIBUTING.md — possible, but CLAUDE.md is the documented convention Claude Code auto-loads, so it reaches the tool without extra configuration.
Use case
We use Claude Code on this repo for issue triage and PR reviews (the
claude.ymlandclaude-code-review.ymlworkflows are already wired up). Each session currently has to re-discover basic context — that this is a dual-language monorepo with parallel Python and TypeScript implementations, where the build/lint/test commands live, the orchestrator/classifier/agent/storage/retriever architecture, and the CI-enforced issue-first PR policy.Without a
CLAUDE.mdat the repo root, every run wastes tokens and time re-learning the same facts, and is more likely to miss conventions (e.g. opening a PR without a linked issue, or making a change in one language tree but not the parallel file in the other).Solution / User experience
Add a root-level
CLAUDE.mdthat captures:python/+typescript/feature-parity expectation and the rename history (multi-agent-orchestrator→agent-squad,awslabs→2fastlabs).make code-quality,make test,npm run lint,npm run coverage, single-test invocations, theprebuildversion-file quirk).AgentSquadorchestrator,Classifier,Agenthierarchy,ChatStorage,Retriever, plus the compositeChainAgent/SupervisorAgentpatterns.*Optionsdataclass pattern,try/except ImportErrorgating for optional extras.After: Claude Code sessions load this context automatically and produce higher-quality, convention-aware PRs and issue responses on the first pass.
Alternative solutions
CONTRIBUTING.md— possible, butCLAUDE.mdis the documented convention Claude Code auto-loads, so it reaches the tool without extra configuration.