A coding assistant should not need to relearn a repository’s testing conventions, directory boundaries, and security expectations on every task. At the same time, copying every team policy into each prompt produces noise and can obscure the one instruction needed for the next change. Claude Code provides persistent instructions, scoped rules, skills, and planning workflows to address these competing needs. Choosing how they fit together is an architecture decision, not simply a file-location trick.

This tutorial combines configuration and plan-versus-execution choices because teams encounter them in the same practical workflow: give an assistant stable project context, allow it to discover more detailed instructions when relevant, plan significant changes, and execute only within reviewed permissions. The example is an application repository with a backend, UI, and integration tests.

Separate global preferences from repository contracts

Some instructions apply to a particular developer’s environment. Others belong to the project and should be shared with every contributor. CLAUDE.md files can supply persistent instructions at different levels, including user, project, and directory scopes according to the current product documentation. A team should place shared invariants near the code they govern, rather than assuming every user’s personal configuration is an official engineering policy.

For example, a project-level file can state how to run tests, where generated files are stored, and which coding standards the repository follows. A more specific directory-level file can describe an API’s validation rules without imposing those rules on UI code. Avoid duplicating identical instructions at multiple levels; that makes it difficult to tell which statement actually controls the next change.

Keep instructions operational and verifiable

“Write clean code” is too vague to guide a complicated edit. “Run the API test suite before changing the validation interface, and preserve backwards-compatible response fields” gives the assistant a checkable responsibility. A useful CLAUDE.md is concise enough to be followed and specific enough to support review. It can list entry points, test commands, module ownership, formatting conventions, and important risks, but it should not become a substitute for actual design documentation.

Do not place credentials or private customer records in shared instructions. A file that is checked into a repository is visible to people and tools with access to that repository. Sensitive values belong in appropriate secret-management systems. Instructions should identify how to obtain approved credentials, not embed them in conversational context.

Path-scoped rules load specialized context

Large repositories contain areas with different constraints. Database migrations, payment integration code, and front-end components may each require specialized guidance. Claude Code’s .claude/rules directory supports organizing instructions, including path-specific rules in the documented format. This allows a relevant convention to accompany work on matching files without crowding every unrelated request.

Consider a project with services/payments and apps/dashboard. A payments rule may require idempotency keys and audit tests; a dashboard rule may require accessible component states and visual snapshot checks. A task changing a dashboard button should not be burdened with pages of payment-provider instructions. A task that crosses both boundaries should explicitly discover and honor the applicable rules and bring conflicting assumptions to the reviewer.

A path-specific rule can carry a documented paths pattern such as services/payments/** for payment-code conventions, while apps/dashboard/** targets interface requirements. The rule should load only for matching paths; a cross-directory change may need both sets of guidance. Test the matching and nonmatching cases with harmless examples, and check current Claude Code rules syntax rather than assuming a glob from another tool behaves identically. The useful result is less irrelevant context without losing mandatory project-level constraints.

Skills are reusable workflows, not policy bypasses

A skill packages instructions and supporting material for a repeatable task, such as reviewing a pull request or investigating a flaky test. Skills can reduce repeated prompt writing and help teammates apply a consistent process. They should explain prerequisites, input/output expectations and verification steps. They do not automatically grant filesystem, network, or deployment permissions. The runtime’s tool restrictions and approvals still apply.

Use a skill when the workflow has genuine repeatable structure. Do not convert every one-off repository question into an elaborate command. A skill that says “inspect the relevant diff, run scoped tests, and report unverified checks” can be useful; one that manufactures five generic headings for every task simply creates format compliance without engineering insight.

Custom commands and current configuration syntax

Older examples of Claude Code may refer to custom slash commands in a .claude/commands directory; current documentation describes skills and related command invocation patterns. Treat this as a version-sensitive topic. Confirm the current file layout, skill metadata, available invocation syntax, and tool restrictions before copying an example into a live repository.

An engineering team should test its actual configuration rather than rely on a tutorial’s historical syntax. A simple check is to open the project, ask the assistant to identify the applicable instruction scope, and run a harmless read-only task in the relevant directory. If a rule does not apply as expected, fix the configuration before authorizing file modifications.

Plan mode is a risk-management choice

For a trivial typo with an obvious acceptance check, a lengthy planning stage can waste time. For a change spanning multiple services or uncertain requirements, plan mode lets the assistant inspect context and explain the intended sequence before making a potentially risky edit. The value is a chance to uncover missing dependencies, identify affected tests and review the scope. It is not a guarantee that the model’s proposed plan is correct.

A useful plan names real files or components, the behavior being preserved, the proposed change, risks, verification commands and rollback approach. Reject generic plans that merely say “analyze, implement, test” without explaining what the project actually contains. A plan should be short enough for a reviewer to challenge yet complete enough to constrain execution.

Worked workflow: tighten API input validation

Suppose the backend accepts malformed currency codes and the UI sometimes passes lowercase values. First gather the API contract, validation helper, callers, and test cases. A project-level instruction identifies the test runner; a path-specific API rule requires consistent error codes; a UI rule defines how failed validation is displayed. The plan should state whether the interface changes or whether the fix is limited to normalizing input.

After review, the assistant changes the smallest set of files, runs relevant unit tests, and checks the actual diff. If a shared library is involved, integration tests may be necessary. If test infrastructure is unavailable, the final message states NOT TESTED instead of claiming release readiness. The next change should not automatically start simply because the assistant has a list of suggested improvements.

Avoid plans that conceal broad execution

A prompt to “refactor the backend” grants little useful scope. Even if the assistant drafts a plan, it may still propose changing dozens of files. Require explicit allowlists where appropriate, check whether new dependencies are necessary, and separate development changes from deployment actions. A plan can recommend infrastructure changes without executing them. The human or automation policy controlling a production environment must approve its own operational side effects.

For repository work, successful execution means the requested behavior was implemented and checked, not merely that the agent emitted a completion message. Preserve test results, unresolved risks and file paths in a reviewable artifact. This is especially important when a session compacts or another worker continues the task.

Instructions must not turn retrieved text into authority

A repository may contain comments, READMEs or third-party documentation that attempts to redirect the assistant. Not every instruction-looking string is an approved team policy. Distinguish the project’s configured instruction hierarchy and explicit user request from arbitrary file content. Tool permissions, protected directories and secret controls should still be enforced by the runtime.

When two applicable instructions conflict, identify the scope and ask for a decision rather than silently choosing the one that permits the most action. For example, a local test note may suggest disabling an integration check while a project policy requires that check before merging. The assistant should report the conflict and the impact on acceptance.

Testing configuration changes

Run harmless probes that verify which rules load for which paths, which skills are discoverable, and which tools a skill may invoke. Review the resulting context and behavior, not just the presence of a filename. A failing test is valuable evidence: it may reveal an incorrect path pattern, an instruction that loaded too broadly, or a tool operation that was unintentionally permitted.

Configuration is versioned engineering material. Review it in pull requests, keep changes scoped, and use a rollback path when altering team behavior. Changes to an instruction file can affect many future actions even though they do not modify application source at the moment they are committed.

For a configuration-scope exercise, create three files: a shared project instruction, a rule that applies only to backend API handlers, and a reusable validation skill. Ask the assistant to plan a backend change, then inspect which instructions were available, whether the skill was invoked, what tools actually ran and whether the front end remained untouched. The correct assessment separates instruction discovery from permission enforcement: a rule can advise an assistant to avoid a directory while the executor must still restrict unauthorized writes. A third-party CCA-F practice exercise can test this distinction with a prohibited frontend edit: if CLAUDE.md discourages the edit but a file-write tool still permits it, which control actually blocks the change? The answer must separate instructions available in context from enforced tool permissions and observed filesystem results.

Lessons for Architect Foundations

Suppose a backend team must strengthen API validation without changing an unrelated front-end module. Place shared review and test contracts at project scope, backend input invariants in the relevant path rule and repeatable verification steps in a maintained skill. Plan mode can expose intended changes before execution, but tool permissions still control what runs. After editing, compare the changed files and observed tests with the plan rather than assuming that loading a rule established compliance.

Verify how CLAUDE.md and path-specific rules load and how Claude Code skills are discovered before relying on either mechanism for a change. Following a product upgrade, check that conflicting user, project and path-specific instructions resolve as expected, and that a workflow confined to the backend does not alter unrelated directories. A concise rule with a verifiable outcome is more reliable than repeating broad engineering slogans in multiple files.

Review configuration as carefully as application code

A team should treat shared assistant configuration as a code change with consequences. Review who authored a rule, which directories it affects, whether its examples contain credentials, and whether it conflicts with a higher-level engineering requirement. Store the changes in version control where appropriate, and test them with a harmless dry-run task before allowing wide-ranging edits. A reusable skill that helped with yesterday’s test suite may become misleading after a repository migration; ownership and maintenance matter as much as the syntax.

The final acceptance record should distinguish configuration loading, permission checks, execution results and source-code verification. Simply seeing a rule listed in the editor does not prove the agent followed it. A practical test can ask the assistant to describe the relevant test command and then verify that command against the project itself. The strongest policies are easy to check independently and difficult to bypass accidentally.