AGENTS.md and CLAUDE.md — concise repository context

Repository instructions should give every fresh agent the same operational truth: project layout, safe commands, boundaries, and proof required before completion. For Scorecard Q9, a long manifesto is weak evidence. The strongest setup has one concise shared core, thin tool-specific adapters, scoped detail, and a recurring test that confirms each supported client loaded the intended rules.

Scorecard Q9: How is institutional codebase knowledge configured?

Max-score evidence: versioned, scoped instructions whose discovery and behavior are tested in Claude Code, Cursor, and Codex.

Use a shared core with explicit adapters

Start with AGENTS.md as the human-readable project contract:

# Repository operating contract

## Structure
- Application code: `src/`; tests: `tests/`; docs: `src/content/docs/`.

## Safe commands
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`

## Boundaries
- Never deploy or access production data from a local agent session.
- Ask before changing dependencies or public APIs.

## Completion evidence
- Report changed files, commands run, results, and unresolved risks.

Then adapt discovery without duplicating policy:

Tool	Project instruction entry point	Scoped detail
Claude Code	CLAUDE.md or .claude/CLAUDE.md; it can import @AGENTS.md	.claude/rules/*.md, optionally with paths frontmatter
Cursor	root AGENTS.md or CLAUDE.md	.cursor/rules/ with application modes or file patterns
Codex	AGENTS.md, discovered from repository hierarchy	More-specific nested AGENTS.md files where needed

Sources: Claude Code memory and rules, Cursor rules, and Codex AGENTS.md.

For Claude Code, the adapter can be one line:

@AGENTS.md

Add Claude-only or Cursor-only rules only for real client differences. Do not copy the full shared contract into three files; copies drift.

Keep instructions at the right layer

• Put always-relevant facts, commands, and safety boundaries in the root contract.
• Put path-specific conventions beside their code or in the client’s scoped-rules mechanism.
• Put multi-step procedures in skills so they load on demand.
• Put hard enforcement in permissions, hooks, branch protection, and CI. Instruction files guide behavior; they are not a security boundary.
• Put task state in intent.md, spec.md, and plan.md, not in a permanent repository rule.

Test a fresh session

Run the same diagnostic in each supported client after changing instructions.

Copy-paste prompt — discovery:

Before editing anything, list the repository instruction files you loaded, summarize the safe build and test commands, and name every production boundary. Cite each answer to its source file.

Copy-paste prompt — scoped rule:

Inspect src/auth/ without editing it. Which repository-wide and auth-specific instructions apply? If no scoped instruction loaded, say so explicitly.

Copy-paste prompt — contradiction audit:

Review all instruction files that apply from this directory to the repository root. Report duplicate, stale, vague, or conflicting rules. Propose the smallest consolidation patch and do not change runtime code.

Record expected answers in a lightweight test checklist. A newly added command is not trusted until it runs successfully in a clean checkout or the documented local environment.

Failure pattern: context that cannot be verified

Common failures are copied files that disagree, prose such as “test thoroughly” with no command, stale paths, secrets in personal instructions, and a root file so large that critical rules are hard to find. Another failure is assuming every client discovers every vendor-specific directory. Test discovery rather than relying on a portability claim.

Completion evidence

• The shared core names structure, safe commands, boundaries, and required proof.
• Tool-specific files contain only true differences or imports.
• Every documented command was executed in the supported environment.
• A fresh session in each client reports the expected instruction set.
• The owner and review cadence are recorded near the contract.

Continue with durable artifacts

Artifact chain Move task state through reviewable intent, specification, plan, diff, and evidence.

Q6 · Agent skills Move conditional procedures out of always-loaded context.

Q12 · Agent hooks Enforce selected invariants with tested controls.