The same Claude Code assistant can behave very differently in two repositories without changing models. One project may have clear instructions about tests, generated files and forbidden actions; another may have a sprawling instruction file that contradicts itself and hides important requirements under pages of background material. An architect has to decide what instructions should always be present, what should appear only for certain files, and what belongs in a reusable workflow invoked for a specific task.
This is part of the Claude Code Configuration & Workflows domain of Claude Certified Architect – Foundations. Anthropic uses CCAR-F as the formal exam code; CCA-F is the site shorthand for the same examination. The exam expects practical judgment about CLAUDE.md, modular rules, skills, planning and iterative work rather than memorization of one repository layout.
Start with the smallest durable project memory
A good CLAUDE.md answers questions that a developer would otherwise need to repeat in every session. It might explain where tests live, which commands are safe, where generated code should not be edited, how to run linting and what evidence is required before a change is declared complete. These are durable project facts and expectations, not a running transcript of everything anyone has ever discussed about the repository.
Consider a team maintaining a billing service. Its project instructions might state that monetary values are represented in integer minor units, that integration tests require disposable test accounts, and that payment writes must never be executed against production from a development session. Those points change how a coding agent should interpret nearly every task. A temporary release checklist, by contrast, is likely better stored as a task-specific workflow rather than in memory loaded on every request.
Instruction hierarchy matters. Personal or user-level preferences, project instructions and directory-specific files can all contribute context in supported Claude Code configurations. When two files appear to contradict each other, the team should not assume that more text will produce better compliance. Identify who owns each rule, which scope should control and whether a conflict must be fixed in the repository rather than resolved repeatedly by the model.
An overly long root instruction file also consumes context before a task begins. Developers should remove redundant explanations, keep core rules easy to find and link or import modular documentation when appropriate. CLAUDE.md is a navigation and governance aid, not an alternative to executable tests or protected deployment credentials.
Use imports to separate stable rules from reference material
As a repository grows, some instructions become too specialized for its root file. A service may have separate API-contract conventions, database migration procedures and documentation requirements. An import structure can keep these explanations in appropriately named files while allowing the project to present relevant context to Claude Code through documented mechanisms such as @import.
Modularity is valuable only when users can understand where an instruction comes from. A rule buried in an imported document that conflicts with a newer project rule produces avoidable ambiguity. Make the ownership and purpose of each module clear, and keep imported paths under version control when team consistency matters. Do not use imports as a way to smuggle credentials, secrets or sensitive production configuration into a prompt.
A practical structure might place the unchanging repository map and allowed test commands in the root file; API style in a separate reference; and a workflow for database migrations in a dedicated skill. The choice is guided by when information is needed. If every change requires a rule, it belongs somewhere reliably available for every relevant task. If it is specialized material needed only when a developer invokes that task, loading it unconditionally increases noise.
Import graphs should also be reviewed when teams rename directories or restructure the repository. An instruction that silently stops loading is a configuration defect, even when the coding assistant still produces plausible-looking work. A test that asks Claude to locate the relevant convention can reveal missing context before a real migration depends on it.
Path-specific rules prevent irrelevant instructions from dominating
A repository that contains TypeScript, SQL migrations, deployment YAML and Markdown documentation does not need the same detailed instructions for every file type. Path-scoped rules under .claude/rules/, using supported frontmatter path patterns, can attach specialized guidance to the files it concerns. That makes a narrowly relevant rule more visible when it matters and less distracting when it does not.
For example, a migrations rule may explain naming, reversibility and expected data checks for files under db/migrations/. A frontend rule may describe accessibility expectations for UI components. A documentation rule may explain terminology and review requirements for public articles. Combining all three in a generic “always do everything” paragraph creates conflicts and unnecessary context.
Path patterns must be reviewed with the same attention as build globs. A pattern intended for nested migration files can miss a newly created directory; a broad pattern can attach sensitive operational instructions to files that do not need them. Testing with representative paths is more reliable than merely confirming a rule file exists.
Directory-specific CLAUDE.md and conditional path rules solve overlapping but different organization problems. The former can give local context to a component or package. The latter can express conventions based on matched files or types. Choose based on repository shape and ownership, not because one feature sounds more advanced.
The important security limit is unchanged: conditional guidance is not a permission barrier. A rule that says “never edit deployment secrets” can improve decisions, but an enforced write restriction must come from the actual permission model or an appropriate deterministic gate.
Skills and commands should perform recognizably different work
A team often repeats a procedure such as checking a pull request, investigating an incident or preparing a release. A skill can package the instructions and reference material for that workflow so the developer does not reconstruct it from memory. A skill’s SKILL.md describes what it does, when it is appropriate, and which supporting information belongs to that task.
A good skill has a coherent purpose and an observable completion condition. A database-migration review skill might check reversibility, locking risk, compatibility during deployment and whether a rollback can be tested without destructive production actions. A documentation-review skill might inspect links, grammar and factual citations. These are different from ordinary repository facts that should remain in CLAUDE.md.
The exact mechanics of custom slash commands and skills have evolved across Claude Code versions. Historical configurations use .claude/commands/; skills have their own structure and metadata. Options such as context: fork, allowed-tools or argument-hint may matter to the exam blueprint, but an architect should validate their behavior against the installed version rather than treating an old example as an immutable interface contract.
context: fork is useful when an invoked task benefits from an isolated working context and its result can be summarized back to the parent workflow. It is a poor substitute for a simple one-step procedure, because isolation adds handoff overhead and makes assumptions harder to see. allowed-tools can narrow a workflow’s supported tool surface where available; it does not grant authorization to a backend that would otherwise reject the call. These details matter when designing a reusable team workflow.
A short, precise skill is more useful than one that promises to “make the code perfect.” Name the input artifacts, required checks and stop conditions. If a tool or data source is unavailable, the skill should report that limit instead of labeling the requirement as passed.
Planning and exploration should depend on the work’s risk
Claude Code can help a developer explore a codebase and propose a plan before changing files. That approach is especially useful when the task touches multiple packages, uncertain dependencies or sensitive deployment paths. It allows humans to inspect scope and assumptions while the repository remains unchanged.
A small documentation typo does not need a large architecture proposal. A production authentication refactor usually does. The correct decision is not always “use plan mode.” It is to assess the blast radius, ambiguity and ability to verify the outcome. A plan that merely narrates intended changes is weak unless it identifies dependencies, measurable checks and rollback points.
The Explore subagent or another restricted research workflow can inspect relevant files without unnecessarily editing them. Its output should describe the observed repository state, important file paths and remaining uncertainties. If its context is isolated, pass back stable facts rather than a claim that everything was examined. This fits the broader Claude Code workflow design question: the safest approach is proportionate to the task, neither maximal delegation nor thoughtless direct execution.
A concrete example is a library upgrade. First identify the version in use, callers affected and existing test coverage. Then plan targeted changes and run static checks in a disposable branch. If the dependency is used by production authentication, require review and deployment controls beyond those for a leaf development tool. The architecture of the workflow should follow consequences rather than the convenience of a command.
Keep deterministic policy outside advisory instructions
Project rules, skills and prompts guide a model; a protected branch, secret manager, authorization service or test runner enforces a separate external fact. Confusing these roles produces “prompt-only security”: the assistant appears compliant until it encounters a new phrasing or a compromised tool result.
Consider an instruction that says no test may be skipped when the release is built. A real release pipeline should fail if tests fail or do not run, independent of the agent’s report. A skill can specify which tests to execute and how to interpret the output; the CI system decides whether a commit may progress. A hook can help run a check at a defined point but should not be mistaken for the entirety of a security boundary.
The same principle applies to sensitive file access. An agent may be told that a secret is restricted, but a controlled environment should also prevent access to that secret through tools granted to the session. If source content tries to override the project’s trusted instructions, the application still needs defensible permission boundaries. The MCP tool contract and backing authorization model determine what external actions are allowed, not the confidence of the model’s explanation.
Context volume is another practical governance issue. A skill that dumps an entire API manual into every request can crowd out the actual acceptance criteria. Use concise purpose-built references and fetch additional documentation as the task genuinely requires it. This preserves attention for the evidence that matters when the work is being verified.
Make configuration testable for the next developer
A configuration should survive more than one successful demonstration. Test it with a clean checkout, a developer whose personal settings differ, a directory that matches a path rule, a directory that should not match, and a skill invoked with missing prerequisites. Check whether the agent loads the expected rules, asks for appropriate approval and records which tests actually ran.
The QA artifact could be as simple as a small matrix with example file paths and expected conventions, a summary of available skills and a list of permissions that must not be granted. For sensitive workflows, also check how the agent responds when a tool fails or a user interrupts execution. A procedure that works only when every call succeeds is not production-ready.
Finally, review the human experience. Engineers should know where to change an instruction, how to debug conflicts and how to tell an advisory preference from an enforced rule. The strongest CCA-F design answer will identify the correct scope and mechanism for a requirement: a persistent project convention, conditional file rule, reusable skill, deliberate plan, hook or external control. Putting the right instruction in the right place is more valuable than making any single prompt longer.