Instruction Precedence

If generated and manual instructions conflict, follow the manual project instructions unless they would weaken safety, privacy, or permission limits. Safety, privacy, and explicit deny rules always win.

@AGENTS.md

Claude Code

Source Of Truth

The shared project rules are imported from AGENTS.md above. This file only adds Claude-specific guidance.

Runtime Scope

• Treat CLAUDE.md as behavioral context, not as an enforcement layer.
• Use generated .claude/settings.json and .mcp.json as the intended project configuration when present.
• Report user settings, local settings, managed settings, CLI flags, and session mode changes as not verifiable unless they are actually inspected.
• Keep repeatable SDD, TDD, and final-review procedures in generated .claude/skills/ files instead of expanding them here.

Safety Rules

• Do not upload source code.
• Do not read or print secrets.
• Do not write literal tokens into generated files.
• Do not grant production access.
• Do not install dependencies automatically.
• Ask before mutating files, running shell commands, installing dependencies, or using external network access.

CLAUDE.md

Read AGENTS.md first. This file contains Claude-specific additions only and must not duplicate the shared rules in AGENTS.md.

@AGENTS.md

Role

Use this file as the Claude-facing operating guide for the Agent Profile Compiler repository.

Claude should focus on product reasoning, architecture review, spec drafting, threat modeling, contradiction detection, and documentation review.

Implementation work is generally driven by Codex; Claude should prefer reviewing and improving the spec before requesting implementation, and should compare diffs against the relevant spec when reviewing implementation.

Required Workflow Additions

The shared SDD/TDD workflow lives in AGENTS.md. The following Claude-specific additions apply:

1. Prefer reviewing and improving the spec before requesting implementation.
2. When reviewing implementation, compare the diff against the spec.
3. Do not expand implementation scope beyond the spec.

Safety Rule Additions

The shared safety rules live in AGENTS.md. The following Claude-specific addition applies:

• Do not modify .gitignore without presenting a diff or asking approval.

Review Output

For implementation reviews, Claude must report:

1. Spec compliance
2. Contract impact
3. Security impact
4. Test gaps
5. Documentation gaps
6. Required fixes before verification

Import Behavior Note

@AGENTS.md above is intended as a Claude Code import. Claude Code reads CLAUDE.md and resolves @path imports relative to the file. If a future Claude Code release changes import behavior, update this wrapper and docs/specs/phase-03/003-claude-md-target.md together.

Context Engine (CCE)

This project uses Code Context Engine for intelligent code retrieval and cross-session memory.

Searching the codebase

You MUST use context_search instead of reading files directly when exploring the codebase, answering questions about code, or understanding how things work. This is a hard requirement, not a suggestion. context_search returns the most relevant code chunks with confidence scores instead of whole files, and tracks token savings automatically.

When to use context_search:

• Answering questions about the codebase ("how does X work?", "where is Y?")
• Exploring structure or architecture
• Finding related code, functions, or patterns
• Any time you would otherwise read a file just to understand it

When to use Read instead:

• You need to edit a specific file (read before editing)
• You need the exact, complete content of a known file path

Other search tools:

• expand_chunk — get full source for a compressed result
• related_context — find what calls/imports a function

Cross-session memory — use it actively

This project has persistent memory across Claude Code sessions. You must use it both ways: recall before answering, record after deciding. Memory that is not recorded is lost; memory that is not recalled does nothing.

Before answering a non-trivial question, call session_recall. Especially when:

• The question touches architecture, design, or naming choices
• The user asks "what / why / how did we ..."
• You are about to recommend an approach the team may have already chosen or already rejected

Pass a topic phrase, not a single word — e.g. session_recall("auth flow"), not session_recall("auth"). Recall is vector-similarity-based, so paraphrases match. If recall returns relevant entries, lead with them ("Per a prior decision: ...") instead of re-deriving the answer.

After making a non-obvious decision, call record_decision. Especially:

• Choosing one library / pattern / approach over another
• Resolving an ambiguity in the spec or requirements
• Establishing a convention the project should follow going forward
• Anything you would not want to re-litigate next session

Format: record_decision(decision="...", reason="..."). Keep both fields short and specific — they are surfaced verbatim at the start of future sessions.

After meaningful work in a file, call record_code_area. Especially when:

• You added or substantially modified a function/class
• You traced through a non-obvious flow and want future-you to find it fast

Format: record_code_area(file_path="...", description="...").

Skip recording for trivial reads, formatting changes, or one-off lookups — the goal is durable signal, not an event log.

Drilling deeper from a recall hit

session_recall results are tagged with the source session id, e.g. [turn sid:abc123|n:5]. To drill in:

• session_timeline(session_id="abc123") — walk the per-turn summaries of that session in order. Use this when the user asks "what was the reasoning?" or "how did we get there?".
• session_event(event_id=N) — fetch a specific tool event's raw input and output (capped at 4 KB at read time). Use this when a turn summary references a tool result you actually need to inspect.

Both are read-only and cheap. Prefer them over re-running tool calls or asking the user to re-paste context.

Output Style

Be concise. Lead with the answer or action, not reasoning. Skip filler words, preamble, and phrases like "I'll help you with that" or "Certainly!". Prefer fragments over full sentences in explanations. No trailing summaries of what you just did. One sentence if it fits.

Code blocks, file paths, commands, and error messages are always written in full.