Making repositories more AI-proficient with Claude Code

Most teams today open Claude Code against a repo and start asking for features. Nothing is wrong with that impulse. What goes wrong is the foundation: without a structured project briefing, you get slow iterations, wrong architectural patterns, and the same class of mistake on day ten that you saw on day one. I once asked for a navigation component and got a default export in a codebase that only ever used named exports. Thirty seconds of output, five minutes of repair, and a reminder that the model does not magically know your repo—it only knows what you (and your files) tell it. That gap is where context engineering earns its keep.

Ujja, writing on DEV Community about a week with Claude Code, describes CLAUDE.md as a kind of memory anchor—a stable place the tool can return to so each session does not start from zero. That metaphor matches how I think about the file: not a README replacement, but living documentation whose consumer is both humans and the agent. Pair that idea with Anthropic’s extension model (project instructions, skills, subagents, MCP) and you get a practical stack for monorepos.

The framework below is four layers deep—root instructions, rules and commands, reusable scaffolding, and MCP bridges—plus workflows for scoping sessions and recovering when things drift. I cite sources throughout; where product paths or names shift, defer to the official Claude Code documentation.

---

Foundation: the four-layer extension system

Anthropic documents Claude Code as extensible along several axes: project memory (CLAUDE.md and related instruction files), skills and automation that bundle repeatable workflows, and MCP for tools that speak to external systems. Enterprise writeups often stress the same throughline: your instructions are not an afterthought—they are part of the product surface area for the agent.

Skywork AI’s 2025 notes on large codebases emphasize that CLAUDE.md-style files tend to be loaded into context up front. That is powerful and dangerous: everything you put there competes with code, retrieved files, and tool output. The design goal is not maximal documentation; it is high-signal constraints the model must not forget.

Layer 1: CLAUDE.md at the project root

What it is: A structured knowledge file the tool loads early in a session. Think of it as API documentation for the agent: endpoints are your commands and packages; schemas are your types and data contracts; error codes are the things that must never happen silently (for example, skipping tests or touching a compliance boundary).

Why it matters: GUI-first assistants often infer more ambiently from open editors and search. Claude Code’s bargain is different: you curate a briefing. When that briefing is sharp, you spend less time re-explaining and more time reviewing correct work.

Ujja’s week-with-Claude-Code writeup is useful here for tone, not mysticism: treat the file as something you iterate as you discover friction. Each time you correct the same mistake twice, that is a candidate line for CLAUDE.md—not a lecture, a constraint the model can obey on the next session.

A practical skeleton:

## Tech stack
- Framework/runtime versions
- Data stores, auth, hosting

## Repository layout
- Where apps vs packages live
- What is generated vs hand-written

## Code standards
- Export style, typing rules, file naming
- Test runner and coverage expectations

## Do not touch without human review
- Compliance-sensitive paths
- Infra with external approvals

## Development workflow
- Install, dev server, test, typecheck, lint

Pro practice: Put a last updated line at the top and treat edits like a changelog entry. Review quarterly or when onboarding feedback repeats the same confusion—those repeats are signals your anchor drifted.

Layer 2: Rules, slash commands, and small automations

This layer is for namespaced, repeatable actions: a command that runs the same lint-plus-typecheck-plus-test sequence before a PR, or a checklist-driven review for risky modules. Shrivu Shankar’s deep tour of Claude Code features makes the broader point: features like context monitoring and disciplined session flow matter as much as raw model capability. The failure mode here is cultural rather than technical—if you maintain twenty bespoke slash commands, people spend more time remembering incantations than describing intent. Keep the set small and obvious; let CLAUDE.md carry philosophy, and commands carry mechanical repetition.

Layer 3: Scaffolding and skills that shape output

Vuong Ngo’s writeup on scaling AI-assisted development argues for scaffolding as the lever that stops monorepo pattern chaos: generate the file tree and boilerplate with your conventions baked in so review is about logic, not style archaeology. In practice that might be a template for React components with named exports, colocated tests, and a fixed import path alias—whatever your org repeats weekly. The win is moving correctness left into generation time.

Layer 4: MCP servers

MCP connects the session to external truth: issue trackers, CI status, documentation portals, controlled database reads. Skywork AI makes the same warning about context budget: heavy MCP payloads crowd out the code you actually need in window. Use MCP where it removes ambiguity (for example, “what failed in the last workflow run?”), not as a substitute for reading the repo.

---

Deep dive: mastering CLAUDE.md

Treat CLAUDE.md as a context API

Good APIs are minimal, versioned, and explicit about failure. Your instruction file should be the same.

• Minimal: Every sentence should change behavior. If it is nice-to-have history, move it to human docs.
• Precise: Prefer examples over vibes. One short “do / don’t” pair beats a paragraph of adjectives.
• Versioned: A date header and a note when a breaking workflow change lands (“as of 2026-03, migrations require review”).
• Constrained: List forbidden zones and legacy pockets honestly. Agents are optimistic refactorers; your job is to channel that energy.

Illustrative excerpt (composite—not copied from any single employer repo):

# Acme Platform (internal monorepo)
Last updated: 2026-03-30

## Architecture (brief)
- Turborepo with a web app, API service, shared UI kit, DB package

## Do not touch
- packages/auth-legacy/** (freeze; replacement in progress)
- infra/terraform/** (change control + weekly freeze windows)
- SQL migrations (require DBA signoff in #platform-db)

## Critical patterns
### Components (named exports only)
(See TypeScript snippet below.)

## Verification
- pnpm typecheck && pnpm lint && pnpm test --run before push

// Preferred: named exports + explicit props type
export interface NavProps {
  items: { href: string; label: string }[];
}
export function Nav({ items }: NavProps) {
  /* ... */
}

// Avoid: default export in this codebase
export default Nav;

Nested CLAUDE.md files at package boundaries

Large monorepos benefit from scoped briefings: a database package might document migration style, transaction boundaries, and how feature flags interact with schema rollouts. Anthropic’s documentation describes how multiple instruction files compose; always reconcile conflicts in favor of the narrower scope when it is clearly about local invariants, and favor the root file for global truths like release policy.

When nested files disagree, treat it like path-specific middleware: the deeper file wins for questions about its subtree (for example, “how do we name migration files?”), while the root file still governs cross-cutting release policy and shared lint rules. If two instructions truly conflict, fix the docs—an ambiguous spec will produce ambiguous code, and the agent will not resolve organizational tension for you.

Another habit that pays off: link to canonical examples inside the repo (“see packages/ui/src/Button.tsx for props typing”) instead of pasting entire files into CLAUDE.md. Links keep the anchor short while still giving the model a concrete target to open. You trade a few extra tool calls for lower baseline noise in every session.

Common pitfalls

---

Workflow patterns: session scoping and checkpointing

One goal per session

A session should have one explicit objective—for example, “migrate middleware from v1 to v2 in the web app,” not “misc improvements.” Name the branch accordingly, paste any supplemental notes alongside CLAUDE.md context, and refuse the temptation to bundle unrelated chores. Scope creep is how windows fill with half-finished refactors.

Pre-edit research pass

Before edits land, ask for a compact plan: architecture summary, affected modules, test plan, risk zones. That mirrors what a senior engineer would demand in a design note, and it tightens the agent’s search space. Shankar’s writing on Claude Code also nudges toward transparent session management—know what the tool has loaded and how much room is left.

Checkpointing and commits

Ask for small commits with imperative messages after each coherent step (auth: validate JWT claims in edge middleware). Micro-checkpoints make rollback and bisecting trivial—especially when a later “helpful cleanup” introduces regressions.

If your team uses squash merges, the intermediate commits still matter inside the session: they are guardrails for the human and for any automation that replays steps. I treat them like feature flags for risk—each green checkpoint is permission to widen scope again.

Context monitoring

When your tool exposes it, inspect context usage mid-session. In a monorepo with a full CLAUDE.md, it is easy to burn tens of thousands of tokens before you open a file. Shankar’s guidance is useful here: prefer understanding what is loaded over opaque compaction that hides what you lost. If you maintain a custom catch-up command that re-reads only what changed since a checkpoint, document it beside your other commands—future you will use it weekly.

---

Anti-patterns and failure recovery

Recovery checklist

• Restate CLAUDE.md constraints verbatim in the next prompt.
• Reset session state if the tool allows; re-seed instructions and a canonical example file.
• Shrink batch size; widen again only after green tests.
• Stabilize flaky tests before large refactors—agents amplify instability.

---

Real-world example at scale (composite)

The scenario below is illustrative: it combines patterns I have seen across large TypeScript monorepos (web UI, API workers, shared packages, infra touchpoints). It is not a literal map of any single employer system.

Setup: “Acme Platform” runs a Next.js web app, edge-hosted API handlers, shared UI and types, and a database package with migrations behind human review. Early Claude Code sessions kept inventing routing and export styles that did not match the internal kit.

Step 1 — Bootstrap CLAUDE.md. The team wrote a root file with stack pins, package map, explicit export examples, forbidden paths, and exact verification commands. Skywork’s reminder applied: every extra paragraph stole space from retrieved code, so they kept prose tight.

Step 2 — Scaffold skills. They added a component scaffold that always emitted named exports, props interfaces, and a colocated test stub. Ngo’s point held: scaffolding beat post-hoc lint lectures.

Step 3 — Scoped session for a feature. Task: real-time notifications on the dashboard. Pre-work enumerated websocket handler, API route, React hook, schema migration, and a fragile connection pool module marked hands off. Implementation order: schema → API → hook → UI → tests, with commits between phases.

Step 4 — Iterate the anchor. After repeated questions about error JSON shape, they added a short Error handling section—another small API contract for the agent.

---

Measuring success and team adoption

Signals

• AI-assisted PRs match style guides without ritual comment threads.
• Scaffolding tasks finish faster with fewer round trips.
• New hires read CLAUDE.md during onboarding and ask better first questions.
• Architects spend less time re-stating non-negotiables in chat.

Adoption checklist

• Root CLAUDE.md reviewed and owned.
• Team agrees to read it before deep Claude Code sessions.
• One documented reset/catch-up flow for long sessions.
• Three to five skills maximum; retire duplicates monthly.
• Stable CI; flakes triaged before bulk refactors.
• Monthly pass to fold new patterns into the anchor.

Timeline expectations: expect a noisy first week, two weeks of tightening as real sessions surface gaps, then a calmer steady state where CLAUDE.md updates become small and deliberate.

---

Closing: from AI-hostile to AI-native

Context engineering is the multiplier behind “Claude Code works here.” The investment is not superstition—it is documentation discipline aimed at a very literal reader. You are not building a monorepo for AI; you are building a system humans and agents can interpret safely.

A practical first step: author CLAUDE.md today, share it with your team, and schedule a monthly trim. For a personal angle on using the same idea on a portfolio codebase, see Building this site—it is a lighter-weight version of the same lesson.

Part 2 goes deeper on token economics: a three-tier documentation model, deduplication rules, and a retrofit playbook—Context efficiency in Claude Code.

---