Repo conventions that keep Claude Code inside your architecture

Agentic coding is Claude Code (or another coding agent) opening pull requests in a live repository. It works when the repo already tells the agent how to build, where to put files, and what to refuse. It fails when those rules live in someone's head, a Confluence page from 2023, or a README that assumes you already know the stack.

We install this on Certification Enablement and on every Embedded engagement. The first week is not "let the model cook." The first week is making the repo literate.

What the agent actually follows

Claude Code will do what the files in front of it say, plus whatever it infers from nearby code. If package.json has a test script that is red, the agent will invent a second way to test. If generated OpenAPI clients sit next to hand-written adapters with no label, the agent will edit the generated files. If secrets are "please don't commit those" in Slack, they will show up in a diff.

So the convention set is small and testable:

1. Commands that pass on a clean checkout. Install, test, lint, typecheck. Exact strings, not "the usual npm stuff."
2. Paths. Where new tools, prompts, eval cases, and MCP servers live. One sentence each.
3. Hard no's. Generated folders, golden files you score against, production credentials, customer exports.
4. Eval entrypoint. If this repo has an agent, CI must be able to fail it. The command belongs next to npm test.

That list is boring on purpose. Boring is what survives a staff change.

CLAUDE.md is the pointer, not the novel

CLAUDE.md is standing policy for Claude Code. It should be short enough that a CI change still gets a matching edit in the same PR. When it becomes a 4,000-word style guide, two things happen: humans stop reading it, and the agent treats the stale parts as optional.

Put the long rationale in CONTRIBUTING.md if you must. Put the commands Claude Code needs in CLAUDE.md. Duplicate nothing.

Layout that keeps diffs reviewable

A layout we see work in TypeScript and Python repos:

• prompts/ or src/prompts/ for system text that production actually loads. Not scattered string literals in six services.
• tools/ or src/mcp/ for schemas and server adapters.
• evals/cases/ for the golden set, with stable ids.
• evals/runner as a real package, not a notebook.
• Generated clients in a named folder the linter already ignores for hand-edits.

The point is not our folder names. The point is that a reviewer can open a PR and know whether the change is a prompt, a tool, a test, or application code. Mixing those in one file is how agentic diffs become unreviewable.

Golden files are production data

If you score the agent against fixtures, those fixtures are not "sample data." They are the spec. Treat them like snapshots: review changes, fail CI when they drift without an explicit update, and never let Claude Code rewrite them to make a new prompt look good.

We fail enablement work that skips this. An engineer who has sat the Developer exam still needs the repo to make the right move the default. Certification does not magically add a evals/ directory.

Week one, not a later phase

On an existing codebase, conventions land before we expect a useful first PR. If SSO, a red pipeline, or missing .env.example eats four days, that is still week-one work. Shipping Claude Code into a repo you cannot build is how you get a clever branch nobody can merge.

After we leave, your engineers keep the conventions because they are in the same PRs they already review. That is the whole product of enablement. A workshop that does not change the repo is a slide deck.