A repository contains an API service, a React storefront and a shared data-access package. Claude Code makes a plausible storefront change but imports a server-only module, breaking the production build. The missing safeguard is not another motivational instruction; it is an accurate description of the repository boundary, backed by a test that detects forbidden imports. Project-level CLAUDE.md instructions explain shared conventions, while scoped rules keep package-specific constraints close to the code they govern. A CLAUDE.md file can tell Claude Code to respect a package boundary, but it cannot make an invalid import safe. A lint rule or build test still has to catch the violation. That makes the Anthropic CCA-F architecture problem less about writing perfect instruction files and more a question about which constraints code must enforce when the assistant gets them wrong.
Write down the repo’s actual contract
A useful root-level CLAUDE.md describes repository layout, package manager, supported test commands, code style and architectural boundaries that apply across the whole project. In the storefront case it should explain that the web application cannot import server-only authentication or database modules and should point to the supported client library. That is actionable information Claude may not infer from file names alone. A list of motivational statements about writing good code would do little to prevent the broken import.
The document should be small enough that its rules remain visible and unambiguous. Refer to established build commands rather than reprinting an entire operations manual. If there are separate paths for linting, type checking and integration tests, name which situations require each. A developer should be able to read the instructions and understand what a correct change looks like. The same principle supports Claude Code workflows: durable project conventions belong in a discoverable source, not in a fragile sequence of chat reminders.
Understand scope before writing nested instructions
Instructions may exist at organizational, user, project and directory-specific levels, depending on the installed Claude Code environment and configuration. Treat their loading rules as an explicit part of the project design. A nested directory may need conventions specific to its language, framework or generated files, while the repository root holds constraints shared across teams. You should not simply duplicate the same guidance in every folder; conflicting copies invite changes that satisfy one file but violate another.
For example, the API service may require a contract test whenever an endpoint schema changes; the frontend may require visual checks for public components; the data package may forbid importing from the UI at all. Those are coherent path-specific rules. When a developer opens a cross-cutting feature, Claude may encounter several applicable instructions. Give precedence deliberately, verify how the installed version loads them and test a change that crosses boundaries. Do not guess that the nearest file always overrides every broader rule without checking the actual behavior.
Keep project knowledge separate from task requests
A useful division of responsibilities places enduring repository constraints in the project file, repeatable specialist procedures in Claude Code skills, and reproducible acceptance checks in noninteractive CI workflows. For example, the file may name the test suite, a skill may describe how to review a migration, and CI must actually run the suite. Keeping those layers distinct reduces duplicated instructions and makes compliance testable.
A user asks Claude to optimize a checkout component. That prompt should define today’s goal; CLAUDE.md should preserve what always matters, such as test commands and known module boundaries. Mixing an urgent one-time workaround into permanent project instructions is dangerous because it may outlive the incident and quietly influence unrelated work. Time-limited exemptions belong in a tracked change or issue with an owner and expiry condition. Otherwise six months later the coding assistant may repeat an obsolete exception.
A common mistake is treating every piece of documentation as an instruction. Architecture notes can be reference material, and customer tickets can contain untrusted requests. Persistent project instructions should be reviewed and version-controlled like configuration, while a task description supplies the immediate objective and acceptance conditions. Neither source grants unlimited filesystem or deployment authority. CI checks, access controls and branch protection must still govern actions with external consequences even when the instruction text is explicit.
Use scoped rules for languages and directories
Suppose a monorepo mixes TypeScript API handlers, Python analytics and infrastructure files. A global directive to use one linter is meaningless across those ecosystems. Put shared principles at the root, then use scoped rules for the relevant file patterns or folders where the tool supports them. The TypeScript rule can name its type-check command and import conventions; the Python rule can explain dependency isolation and test fixtures. A reviewer should not need to search a huge root document to find the one policy that applies to a changed file.
Path scoping also avoids needless context load. A frontend-only change should not absorb a page of database migration instructions unless those migrations are relevant. However, do not use scoping to hide critical cross-cutting rules: secret handling and permission boundaries normally apply everywhere. Test with representative tasks in each directory, including work that modifies both API contracts and client components. Missing instructions at a path boundary can be as serious as contradictory instructions, especially when the assistant confidently follows the only rule it sees.
Put repeatable procedures in skills, not permanent prose
If a release checklist includes ten steps and detailed rollback examples, loading the entire checklist into every session wastes attention. A reusable skill can hold the procedure and expose a concise description, to be loaded or invoked when deployment work is actually happening. By contrast, the root instructions may simply say which skill is the approved path for releases. This distinction separates always-on facts about the project from specialized workflows needed occasionally. It also makes each procedure easier to maintain without changing unrelated coding sessions.
A skill is not automatically a secure permission boundary. It can guide Claude through a review, but production access remains controlled by the hosting and repository systems. A well-designed setup makes that separation clear: instructions establish conventions, skills carry repeatable tasks, and hooks or tool permissions enforce relevant restrictions. The interface can evolve, so verify how discovery and invocation work in the installed Claude Code version rather than assuming a legacy custom command behaves identically to a current skill.
Make changes traceable and reviewable
Project instructions influence many future outputs, so modifying them deserves a review comparable to changing CI configuration. Record the motivation, affected paths and expected behavior. In a code review, show how the old rule allowed a concrete failure and how the new rule would have prevented or detected it. Without an example, an instruction like “prefer efficient code” cannot be tested. Reviewers should challenge vague wording because Claude may interpret it differently across tasks and models.
Version changes matter especially during migrations. If the monorepo switches package managers, a stale CLAUDE.md might tell the assistant to edit the wrong lockfile. Include instruction checks in onboarding and repository maintenance, not merely during agent adoption. An outdated command should produce a test failure or a review finding, not a quiet assumption that the instructions are close enough. The source-controlled file provides history; successful execution of the actual project commands provides evidence of correctness.
Avoid using prose to replace enforced policies
Imagine a policy that prevents committing secrets. Telling Claude not to commit credentials helps, but it cannot guarantee that a generated fixture, debug log or copied environment file contains none. Enforce the policy through repository scanners, access restrictions and protected review steps. Similarly, a statement that production deployments need approval should not be the only obstacle to a tool capable of directly deploying. Use the least privileged credentials compatible with the work and keep privileged actions behind authenticated controls.
For exam scenarios, ask which failure mode is being prevented and which layer has authoritative evidence. A formatting convention can often live in an instruction file. A missing invoice-owner verification needs a runtime permission check. A complete test suite needs CI rather than a promise in chat. Conflating these mechanisms creates false confidence: project instructions improve decisions, but they do not make unsafe behavior impossible. Reviewers need both clear guidance and systems that still reject an incorrect action.
Review a storefront change end to end
The team wants to add shipment status to checkout. At the root, CLAUDE.md explains the monorepo layout and the approved package commands. A scoped frontend rule describes client-only imports; a server rule specifies the shipment endpoint contract and authentication tests. Claude proposes the UI change and API adjustment. The developer checks that the assistant used the shared client library, ran the appropriate tests and did not expose server credentials in browser code. A missing server-only import is caught by static analysis even if Claude’s final explanation sounds convincing.
After the change, the team examines whether the instructions were adequate. If Claude repeatedly misses the same path convention, improve the relevant scoped rule and add a regression fixture. If the failure came from an unenforced security boundary, strengthen the tool or build policy rather than expanding the prose. The output is not just a better instruction file. It is an engineering system in which the assistant has useful context, the repository retains its own invariants and reviewers can trace why a change was accepted.