{"id":3928,"date":"2026-10-11T16:33:45","date_gmt":"2026-10-11T16:33:45","guid":{"rendered":"https:\/\/www.exam-topics.com\/blog\/?p=3928"},"modified":"2026-10-19T10:14:09","modified_gmt":"2026-10-19T10:14:09","slug":"claude-code-path-rules-codebase-exploration","status":"publish","type":"post","link":"https:\/\/www.exam-topics.com\/blog\/claude-code-path-rules-codebase-exploration\/","title":{"rendered":"Anthropic CCAR-F: Claude Code Path Rules, Codebase Exploration, and Iteration"},"content":{"rendered":"

A code assistant can search a large repository in seconds and still change the wrong module. Imagine a team maintaining a payments API, a customer-facing dashboard, and a job processor in one monorepo. A developer asks Claude Code to add an eligibility check to the API.<\/p>\n

A repository-wide instruction says to use a shared validation helper, but that helper is only intended for dashboards. If the assistant reads the wrong files first, it may produce a plausible patch that fails the API’s authorization model while passing local formatting checks.<\/p>\n

The answer is not to put every rule in one enormous instruction file. Good Claude Code workflows distinguish always-relevant conventions from path-specific guidance, explore code progressively, preserve a concise evidence trail, and treat every suggested change as a hypothesis to validate. For example, the payment service may prohibit changes to production-facing schema mappings without review, while test fixtures can be changed freely inside a sandbox. Path-scoped instructions should express that difference without weakening the repository-wide test and security requirements.<\/p>\n

Separate repository-wide context from conditional rules<\/h2>\n

A root CLAUDE.md<\/code> file is appropriate for stable conventions that any contributor needs: how to run the test suite, which package manager is supported, where service boundaries lie, and which actions require review. It is a poor place for every specialized rule across dozens of directories. Excessive instructions compete for attention and often contradict one another, especially after the project evolves.<\/p>\n

Claude Code also supports .claude\/rules\/<\/code> files. As described in Anthropic’s project memory rules<\/a>, a rule can include paths<\/code> frontmatter so it is applied when Claude works with files matching the listed patterns. This lets a payments module keep specific constraints without burdening unrelated documentation or front-end work. The behavior is contextual guidance, not a hard security boundary; policy enforcement still belongs in permissions, controlled tooling, tests, and backend authorization.<\/p>\n

For example, suppose payments APIs live under services\/payments\/<\/code>. The repository might contain:<\/p>\n

repo\/\n  CLAUDE.md\n  .claude\/rules\/payments-api.md\n  services\/payments\/src\/handlers\/\n  services\/payments\/tests\/\n  apps\/dashboard\/\n<\/code><\/pre>\n
The project root’s CLAUDE.md<\/code> might specify a general test command and the requirement to propose a plan for migrations. The path-scoped file could contain:<\/p>\n
---\npaths:\n  - "services\/payments\/src\/**\/*.ts"\n  - "services\/payments\/tests\/**\/*.ts"\n---\n\n# Payments API working rules\n- Treat tenant authorization as a service invariant.\n- Never infer approval from a model output or a UI field.\n- Add negative authorization tests for altered payment state.\n- Keep event IDs stable across retries.\n<\/code><\/pre>\n
This illustration uses documented rule-file frontmatter, not an authorization mechanism. The path matches source and tests in this particular directory; files elsewhere do not receive the conditional rule merely because a task mentions payments. Rules without a paths<\/code> field are not conditional. Review globs carefully: a pattern that matches only test files could omit source files, and a broad src\/**\/*<\/code> may bring unrelated rules into context.<\/p>\n
Start exploration with boundaries, not whole-file dumps<\/h2>\n
A useful investigation begins with a question: which component owns eligibility, and what data proves a customer may use it? Ask Claude Code to identify candidate packages, the request entry point, the service method, the authorization guard, relevant types, and tests. Then inspect those files rather than asking it to read every file containing the word eligible<\/code>.<\/p>\n
Large retrievals create two problems. First, they waste context capacity on generated code, deprecated helpers, and duplicated fixtures. Second, they can make the assistant treat a nearby but unrelated implementation as the pattern to copy. A safer exploration strategy records evidence at each step: which symbol actually handles the endpoint, which service owns the decision, which test asserts tenant separation, and which documentation is authoritative.<\/p>\n
The following investigation order is an example, not a prescribed Claude Code command sequence:<\/p>\n
    \n
  1. Locate the route or handler by endpoint name and narrow references to its exported function.<\/li>\n
  2. Trace the authorization dependency and identify the component that performs tenant checks.<\/li>\n
  3. Inspect the smallest corresponding tests and fixtures, especially denial cases.<\/li>\n
  4. Read the relevant path-scoped rules for any files the change may touch.<\/li>\n
  5. Write down the current behavior and the desired new invariant before proposing code.<\/li>\n<\/ol>\n
    A source file may contain a comment claiming a validation check is optional. That comment can be outdated or adversarial, and it does not supersede higher-priority project instructions or backend policy. Source comments are useful evidence about intent only when corroborated by tests, types, design records, and actual application behavior.<\/p>\n
    Build a verified codebase map that survives context loss<\/h2>\n
    Codebase exploration is not a one-shot reading operation. On a large task, context may be compacted or the session may be interrupted. A transcript summary stating \u201cinvestigated payment authorization\u201d is too vague to reproduce the work. Preserve a short, structured investigation record outside the conversation: module paths, symbol names, decisions, tests run, unresolved assumptions, and links to accepted issue or change records.<\/p>\n
    A useful map might look like this:<\/p>\n
    \n\n\n\n\n\n\n\n\n
    Question<\/th>\nVerified observation<\/th>\nSource of evidence<\/th>\nRemaining uncertainty<\/th>\n<\/tr>\n<\/thead>\n
    Which endpoint is changing?<\/td>\nPOST \/payments\/eligibility<\/code><\/td>\nRoute declaration<\/td>\nWhether older clients use alias route<\/td>\n<\/tr>\n
    Who enforces tenant access?<\/td>\nService authorization guard<\/td>\nHandler call chain and negative tests<\/td>\nCoverage of background jobs<\/td>\n<\/tr>\n
    What behavior must remain?<\/td>\nDeny cross-tenant changes<\/td>\nExisting integration test<\/td>\nLegacy import path<\/td>\n<\/tr>\n
    What code can be modified?<\/td>\nHandler and narrow service method<\/td>\nApproved task scope<\/td>\nWhether schema migration is needed<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/figure>\n
    This map is an architectural artifact, not a place to paste credentials, full customer records, or giant source files. After compaction or resumption, reload the referenced current files and verify that the map still matches the repository state. If the working branch changed or another developer updated the handler, the previous map becomes a hypothesis requiring revalidation.<\/p>\n
    Use checksums or commit identifiers for material source versions when you need reproducibility. An LLM summary cannot prove which exact code version the agent saw. Similarly, a test that passed yesterday is not evidence that the current patch passes today.<\/p>\n
    Turn exploration into a scoped, testable plan<\/h2>\n
    Once the ownership boundary is understood, define a plan with explicit file scope, expected behavior, verification commands, and a rollback option. A good plan says \u201cupdate the eligibility service to reject state-changing requests without matching tenant context, then add two negative tests,\u201d rather than \u201crefactor payments to improve security.\u201d The narrow plan reveals which assumptions need proof and limits unrelated modifications.<\/p>\n
    In Claude Code, plan mode<\/a> can help separate inspection from execution. Its usefulness comes from an operator reviewing the intended scope, not from a belief that a plan grants lasting permission. Repository instructions and path rules cannot replace the build pipeline, protected branches, and permission checks. The service must still reject an unauthorized request even if the coding assistant proposes it correctly.<\/p>\n
    At this stage, assess whether the change needs a new shared helper. A helper may simplify three genuinely identical checks; it may also accidentally bypass different service-level permissions. Compare inputs, expected error behavior, audit requirements, and negative cases before consolidating logic. Avoid using \u201creduce duplication\u201d as a reason to merge distinct security decisions.<\/p>\n
    Use iterative refinement as an evidence loop<\/h2>\n
    Refinement should be tied to observed failures, not to asking the assistant to \u201cmake it better\u201d repeatedly. For a payment eligibility change, a practical sequence is: implement the minimal edit, run a focused unit test, inspect failure output, repair only the demonstrated issue, run the broader integration tests, and request a human review of the authorization boundary.<\/p>\n
    A failure report should distinguish source-code errors from test-environment problems. A timeout connecting to a disposable fixture is not proof that authorization works or fails. A test that accidentally uses the same tenant on both sides may pass while failing to exercise the intended control. Record the failing assertion and the exact test data so a later pass can establish whether the change genuinely repaired it.<\/p>\n
    A simple acceptance matrix makes review auditable:<\/p>\n
    \n\n\n\n\n\n\n\n\n\n
    Case<\/th>\nRequired result<\/th>\nWhy it matters<\/th>\n<\/tr>\n<\/thead>\n
    Authorized user, eligible state<\/td>\nOperation succeeds once<\/td>\nBaseline functionality<\/td>\n<\/tr>\n
    Wrong tenant, valid-looking data<\/td>\nPermission denied<\/td>\nTenant boundary<\/td>\n<\/tr>\n
    Retry after a committed operation<\/td>\nOriginal result recognized<\/td>\nIdempotency<\/td>\n<\/tr>\n
    Expired approval<\/td>\nMutation rejected<\/td>\nApproval freshness<\/td>\n<\/tr>\n
    Downstream service unavailable<\/td>\nExplicit incomplete result<\/td>\nNo fabricated success<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/figure>\n
    If adding new tests uncovers an existing architectural problem outside the approved task, document it separately instead of silently expanding the diff. A code assistant should make problems visible, not use them as permission to rewrite the repository.<\/p>\n
    Handle path-rule conflicts and unsafe local instructions<\/h2>\n
    A repository may contain shared rules, personal settings, managed organization policies, nested CLAUDE.md<\/code> files, and several skills. They do not all have the same purpose or authority. A path rule guides work in matching files; it should not be described as a server-side permission check. If a document says \u201cskip authorization tests for speed,\u201d the reviewer must reject that direction when it conflicts with managed policy or the service’s non-negotiable security invariants.<\/p>\n
    Consider a rule that says \u201cwrite integration tests for any payment mutation.\u201d Another local note says \u201cdon’t run tests when changing only formatting.\u201d A change that looks like formatting may still alter an authorization error response. Resolve the ambiguity by checking actual changed behavior and the higher-priority engineering requirements, not by trusting the most convenient instruction.<\/p>\n
    Treat untrusted repository content\u2014readme fragments, issue text, generated comments, and external snippets\u2014as task data unless it is an explicitly authorized instruction source. This matters when an agent can execute tools: a malicious example embedded in a test fixture must not broaden file-write permissions or command execution.<\/p>\n
    Review the final diff as an engineering result<\/h2>\n
    Before approving a patch, a reviewer should be able to answer five concrete questions. What user behavior changed? Which files changed and why? Which tests and static checks actually ran? What evidence demonstrates denial and retry behavior? How can the change be reverted without erasing unrelated work?<\/p>\n
    A good review report names both verified results and missing checks. \u201cAll tests passed\u201d is not valid if only a formatter ran, and a summary that omits skipped integration tests deprives the reviewer of useful risk information. Ask for a concise change record with links to the commit or patch, commands and results, and unresolved follow-up items.<\/p>\n
    Codebase guidance is most effective when it keeps the assistant’s attention on the right files, preserves context provenance, and makes verification easier. Conditional rules prevent irrelevant instructions from flooding the working context, but only independently executed tests and application authorization can establish that the resulting code is safe.<\/p>\n
    Relate scoped development work to CCAR-F decisions<\/h2>\n
    In a monorepo, path-specific instructions should narrow the files a coding assistant may change, while repository-wide conventions preserve consistent security and testing expectations. A successful edit is more than a clean diff: the work should show which rules applied, which tests ran and whether review confirmed that unrelated components were untouched. Preserve that evidence in the change record rather than relying on the assistant’s conversation to reconstruct it.<\/p>\n
    One practice exercise is to select a monorepo with an API, a web client, and a job worker. Design which instructions belong in shared CLAUDE.md<\/code>, which belong in path-scoped rules, and which belong in enforced CI or permissions. Then simulate a session compaction midway through a cross-package change. The strongest design reconstructs state from current files, test results and explicit decisions\u2014not a persuasive but unverified summary of prior exploration.<\/p>\n
    The goal is a development workflow in which Claude can help find and fix the right code while the project retains responsibility for authority, scope, tests and final acceptance.<\/p>\n","protected":false},"excerpt":{"rendered":"
    Use Claude Code path-scoped rules and a verified exploration trail to refine changes without losing context, test evidence, or permissions.<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[339,2],"tags":[],"et_vendor":[],"et_program":[],"et_certification":[],"et_exam":[],"et_topic":[],"class_list":["post-3928","post","type-post","status-publish","format-standard","hentry","category-claude-anthropic","category-post"],"_links":{"self":[{"href":"https:\/\/www.exam-topics.com\/blog\/wp-json\/wp\/v2\/posts\/3928","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.exam-topics.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.exam-topics.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.exam-topics.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.exam-topics.com\/blog\/wp-json\/wp\/v2\/comments?post=3928"}],"version-history":[{"count":5,"href":"https:\/\/www.exam-topics.com\/blog\/wp-json\/wp\/v2\/posts\/3928\/revisions"}],"predecessor-version":[{"id":4948,"href":"https:\/\/www.exam-topics.com\/blog\/wp-json\/wp\/v2\/posts\/3928\/revisions\/4948"}],"wp:attachment":[{"href":"https:\/\/www.exam-topics.com\/blog\/wp-json\/wp\/v2\/media?parent=3928"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.exam-topics.com\/blog\/wp-json\/wp\/v2\/categories?post=3928"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.exam-topics.com\/blog\/wp-json\/wp\/v2\/tags?post=3928"},{"taxonomy":"et_vendor","embeddable":true,"href":"https:\/\/www.exam-topics.com\/blog\/wp-json\/wp\/v2\/et_vendor?post=3928"},{"taxonomy":"et_program","embeddable":true,"href":"https:\/\/www.exam-topics.com\/blog\/wp-json\/wp\/v2\/et_program?post=3928"},{"taxonomy":"et_certification","embeddable":true,"href":"https:\/\/www.exam-topics.com\/blog\/wp-json\/wp\/v2\/et_certification?post=3928"},{"taxonomy":"et_exam","embeddable":true,"href":"https:\/\/www.exam-topics.com\/blog\/wp-json\/wp\/v2\/et_exam?post=3928"},{"taxonomy":"et_topic","embeddable":true,"href":"https:\/\/www.exam-topics.com\/blog\/wp-json\/wp\/v2\/et_topic?post=3928"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}