Claude Code CLAUDE.md Best Practices for CCA-F

We get this question constantly: "I have Claude Code running, so why does it keep ignoring our conventions?" The answer is almost always a poorly structured CLAUDE.md. Following claude code claude md best practices is the single highest-leverage configuration investment you can make before the CCA-F exam and in production alike. Domain 3 (Claude Code Configuration and Workflows) carries 20% of the exam weight, and CLAUDE.md is its centrepiece.

This guide walks through everything from the three-level hierarchy to MCP integration, parallel session safety, and dynamic workflow patterns. We have mapped each section to the relevant task statements so you can study and ship at the same time.

What is CLAUDE.md and why does it matter?

CLAUDE.md is a plain-text Markdown file that Claude Code reads automatically at session start. It injects persistent context, project conventions, and behavioural rules into every interaction without requiring you to repeat yourself in each prompt. Think of it as a standing system prompt that lives in version control alongside your code.

Per Anthropic's Claude Code documentation, the file is read from three locations in a defined precedence order. Understanding that hierarchy is prerequisite knowledge for Domain 3.

What is the three-level configuration hierarchy?

The hierarchy resolves in this order, with lower levels able to extend but not silently override higher ones:

The exam tests this hierarchy directly. A common distractor swaps levels 1 and 2 or claims sub-directory files override the global file unconditionally. They do not; they extend it. For a deeper treatment, see our concept page on the three-level configuration hierarchy.

How should you structure a project-root CLAUDE.md?

A well-structured project-root file has four logical sections in this order:

1. Project identity -- one paragraph: what the codebase does, primary language, framework version.
2. Conventions -- coding style, naming rules, test requirements, commit message format.
3. Workflow rules -- when to use Plan Mode, how to handle ambiguity, escalation triggers.
4. Tool and MCP configuration -- which MCP servers are active, what each one is for.

Keeping sections in this order matters because Claude Code reads the file top-to-bottom and the model's attention is strongest near the beginning. Burying critical constraints in section four means they compete with everything above them for weight.

Here is a minimal but complete example:

# Project: Payments API

## Identity
Node 20 / TypeScript 5.4 monorepo. Primary service: `packages/payments-core`.
All external I/O goes through the repository's internal SDK at `lib/sdk`.

## Conventions
- Functions: camelCase. Types/interfaces: PascalCase.
- Every exported function needs a JSDoc block with @param and @returns.
- Tests live in `__tests__/` next to the source file, named `*.test.ts`.
- Commits follow Conventional Commits (feat/fix/chore/docs).

## Workflow rules
- For tasks touching more than three files, enter Plan Mode first.
- Never modify `lib/sdk` directly; open a GitHub issue instead.
- If a requirement is ambiguous, ask one clarifying question before proceeding.

## MCP servers
- `github-mcp`: read PR metadata and CI status.
- `datadog-mcp`: query production error rates for the last 24 h.

Notice that the MCP entries are descriptive, not just names. Claude Code uses the description to decide which server to call, so vague entries like - datadog produce misrouting. This is the same principle that governs tool descriptions as a selection mechanism in Domain 2.

How do path-specific CLAUDE.md files reduce token waste?

Every token in CLAUDE.md is loaded into context on every turn. A 2,000-token root file that includes database migration rules is wasteful when Claude is editing a React component. Sub-directory files solve this.

Place a CLAUDE.md in src/db/ that contains only migration conventions. The root file stays lean; the database-specific rules load only when Claude is working inside src/db/. This is the token-efficiency argument for path-scoped rules, and it maps directly to the version control implications concept: sub-directory files should be committed so the whole team benefits.

The exam presents scenarios where a team complains that Claude ignores sub-directory conventions. The root cause is almost always that the sub-directory file was added to .gitignore by accident, so teammates never received it.

How do you integrate MCP servers for real-time production context?

MCP servers are the bridge between Claude Code and live systems. A CLAUDE.md that declares MCP servers correctly lets Claude query production error rates, CI status, or feature-flag state without you pasting that data manually.

The configuration lives in .claude/settings.json (or the user-level equivalent), but CLAUDE.md should document what each server provides so Claude can route intelligently:

{
  "mcpServers": {
    "datadog-mcp": {
      "command": "npx",
      "args": ["-y", "@your-org/datadog-mcp"],
      "env": {
        "DD_API_KEY": "${DD_API_KEY}",
        "DD_APP_KEY": "${DD_APP_KEY}"
      }
    },
    "github-mcp": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Note the ${VAR} syntax for environment variable expansion. Hardcoding secrets into the JSON is a common mistake that the exam flags as a security anti-pattern. See environment variable expansion in MCP config for the full pattern.

With both servers declared, a CLAUDE.md workflow rule like "Before proposing a fix for any runtime error, query datadog-mcp for the error rate over the last hour" gives Claude the context it needs to distinguish a new regression from a known flaky test.

When should you use Plan Mode versus agentic workflows?

Plan Mode and agentic workflows serve different confidence profiles:

The CCA-F exam rewards deterministic solutions over probabilistic ones when stakes are high. Plan Mode is the deterministic gate: it produces a plan you can inspect and approve before Claude touches a single file. Agentic workflows are appropriate once the plan is agreed and the steps are bounded.

A CLAUDE.md rule that encodes this distinction might read:

## Workflow rules
- Tasks rated HIGH risk (schema changes, auth logic, payment flows): use Plan Mode.
- Tasks rated LOW/MEDIUM risk with clear acceptance criteria: proceed directly.
- Risk rating is determined by the engineer opening the task, not by Claude.

How do you scale parallel Claude sessions without git conflicts?

Parallel sessions are powerful for codebase-wide audits, but without coordination they produce overlapping edits and merge conflicts. The CLAUDE.md approach is to define explicit file-ownership rules:

## Parallel session rules
- Each session works in a dedicated feature branch: `claude/<task-id>`.
- Sessions must not edit files outside their assigned path prefix.
- Session 1: `src/api/` | Session 2: `src/workers/` | Session 3: `src/db/`
- All sessions write findings to `scratch/<task-id>.json` before opening a PR.

This pattern maps to subagent context isolation: each session has a bounded scope and a structured output channel. The coordinator (a human or an orchestrating agent) merges the scratch/*.json files and resolves conflicts at the synthesis layer, not the file layer.

The exam tests this with scenarios where parallel agents produce contradictory findings. The correct answer is always to add a convergence step that compares structured outputs, not to run the sessions sequentially to avoid the problem.

How do you configure dynamic workflows for codebase-wide audits?

A dynamic workflow in CLAUDE.md is a named procedure that Claude can invoke when conditions are met. Here is a pattern for a codebase-wide security audit:

## Workflow: security-audit
Trigger: engineer runs `/security-audit` slash command.

Steps:
1. Read `SECURITY_SCOPE.md` to identify in-scope paths.
2. Spawn one subagent per top-level package (max 5 concurrent).
3. Each subagent writes findings to `scratch/security/<package>.json`
   using the schema in `schemas/finding.json`.
4. After all subagents complete, run the convergence step:
   read all `scratch/security/*.json` files and produce
   `reports/security-summary.md` with deduplication and severity ranking.
5. If any finding is rated CRITICAL, open a draft GitHub issue via `github-mcp`.

The schema reference in step 3 is important. Structured output with a shared schema is what makes the convergence step reliable. Without it, each subagent invents its own field names and the synthesis agent cannot deduplicate. This connects directly to the structured context passing pattern in Domain 1.

What are the most effective CLAUDE.md patterns for CI and test generation?

Three patterns consistently outperform ad-hoc prompting for CI and test work:

Pattern 1: Failing-test-first for new features

## Test conventions
For any new exported function, Claude must:
1. Write a failing test that captures the acceptance criterion.
2. Implement the function until the test passes.
3. Add an edge-case test for the null/empty input.
Never mark a task complete if `npm test` exits non-zero.

Pattern 2: Structured CI failure summaries

## CI failure handling
When a CI run fails, query `github-mcp` for the raw log.
Summarise the failure as JSON:
{ "step": string, "error": string, "likely_cause": string, "fix": string }
Write the summary to `scratch/ci-failure-<run-id>.json`.

Pattern 3: Migration script generation

## Migration conventions
Database migrations live in `db/migrations/` and are named
`YYYYMMDDHHMMSS_description.sql`.
Before writing a migration, read the three most recent migration files
to infer naming and style conventions.
Always include a rollback section after the forward migration.

Each pattern replaces a class of manual maintenance work with a deterministic, auditable procedure. The exam rewards this framing: the question is not "can Claude do this?" but "have you specified it precisely enough that Claude will do it consistently?"

How does CLAUDE.md interact with the CCA-F exam domains?

The CLAUDE.md file touches all five domains, but its weight is concentrated in Domain 3. Here is the mapping:

Domain 3 at 20% is the third-largest domain. Candidates who treat CLAUDE.md as a minor detail consistently underperform on the scenario questions that ask "what change to the configuration would fix this behaviour?" For a full domain map, our Claude Code Configuration and Workflows concept library covers all 30 task statements.

What are the most common CLAUDE.md mistakes on the CCA-F exam?

Based on the exam's scenario structure, these are the four patterns that trip up candidates:

1. Putting constraints at the bottom. The model's attention is diluted by the time it reaches line 200. Critical rules belong in the first 30 lines.
2. Vague MCP descriptions. "Use the database server when needed" does not tell Claude when to prefer it over a file read. Specificity drives correct routing.
3. Missing schema references. Workflow steps that produce JSON without referencing a schema produce inconsistent field names across sessions.
4. No escalation triggers. A CLAUDE.md without explicit "stop and ask" rules produces an agent that guesses when it should pause. The three valid escalation triggers concept covers this in detail.

Fixing these four issues moves most CLAUDE.md files from "occasionally helpful" to "reliably deterministic."

If you want to test your understanding of these patterns against exam-style scenarios, our Claude Code Configuration and Workflows concept library has 174 atomic concepts mapped to the five domains, and our adaptive practice exams score on the same 100-to-1000 scale as the real CCA-F, with 720 as the passing bar. AI Skill Certs is independent of Anthropic; we are a prep platform, not an official partner.