1. Core Technical & API Limits
| Feature | Limit / Value |
|---|---|
| Context Windows | 1M tokens (Opus 4.7/4.6, Sonnet 4.6) • 200k tokens (most other active models) |
| Description Length | Tool and Skill descriptions must be under 1024 characters |
| Batch Discount | 50% off vs synchronous requests |
| Batch Window | Up to 24h to process; unfinished requests expire • no latency SLA |
| Batch Correlation | Match results via custom_id only; results are unordered • no multi-turn tool calling inside a batch |
2. Agentic Loop & Orchestration Signals
The orchestrator must drive control flow using structured API signals rather than natural language parsing.
| Signal / Pattern | Meaning |
|---|---|
stop_reason == "tool_use" | The loop continues. Execute the tool, append the tool_result to history, and re-call the API. |
stop_reason == "end_turn" | The only reliable signal for termination. |
| Task Tool | Mechanism for spawning subagents. Coordinator allowed_tools must include "Task" to delegate. |
| Findings → Prompt Contract | Subagents are isolated by default and do not inherit the coordinator's history. Coordinators must explicitly pass findings into the subagent's prompt. |
3. Structured Error & Recovery Framework
Every tool should return structured metadata to enable intelligent coordinator-level recovery.
| Category | Recovery Behavior |
|---|---|
| TRANSIENT | Timeouts or service outages; Claude should attempt a retry. |
| VALIDATION | Invalid input, such as bad email format; agent should clarify with the user. |
| PERMISSION | Authorization gaps; agent should inform the user. |
| BUSINESS | Policy violations, such as refund over limit; agent should communicate the rule. |
isRetryable | Boolean metadata that prevents the model from wasting turns on non-fixable errors. |
4. Prompting & Schema Design Patterns
| Pattern | Use |
|---|---|
| Tool Description Pattern | [Input Shape] + [Canonical Use Case] + [Boundary / DO NOT use for X]. Eliminates misrouting between similar tools. |
| Reasoning-Led Few-Shotting | Include a Why: line in examples to teach the underlying logic so the model generalizes to novel cases. |
| Nullable Fields | Use ["string", "null"] to allow null when data is missing from a source, preventing hallucinations. |
| Extensible Enums | Use an enum field with an other option paired with a separate detail string field. |
5. tool_choice Modes
| Mode | Behavior |
|---|---|
auto | Model may answer in plain text instead of calling a tool. |
any | Model must call SOME tool; use for an unknown document type with multiple candidate schemas. |
{"type":"tool","name":...} | Model must call that specific tool; use for a forced prerequisite step. |
strict: true | Set on a tool definition; guarantees schema-valid tool inputs. |
6. Built-In Tool Selection
| Tool | Use For |
|---|---|
| Grep | Search file CONTENTS. |
| Glob | Find files by NAME pattern. |
| Read / Write | Whole-file operations. |
| Edit | Unique-anchor replacement; fall back to Read + Write when anchors are not unique. |
| Bash | Everything else. |
7. MCP Configuration
| Concept | Rule |
|---|---|
.mcp.json | Project scope — version-controlled and shared with the team. |
~/.claude.json | User scope — personal configuration. |
${ENV_VAR} expansion | Keeps secrets out of the repository. |
| Resources vs Tools | Resources are read-only content catalogs that cut discovery calls; Tools perform actions. |
| Community Servers | Prefer existing community MCP servers for standard integrations over building your own. |
8. Claude Code CI/CD Flags
| Flag / Pattern | Purpose |
|---|---|
-p / --print | Non-interactive mode; prevents CI hangs. |
--output-format json | Machine-parseable output. |
--json-schema | Enforce structured findings. |
| Independent Reviewer | Run review in a separate instance, because a generator will not question its own reasoning. |
| Prior Findings | Include earlier findings in the prompt to avoid re-reporting known issues. |
9. Plan Mode vs Direct Execution
| Approach | When |
|---|---|
| Plan Mode | Architectural decisions, multi-file changes, or multiple valid approaches. |
| Direct Execution | Scoped single-file fixes. |
| Explore Subagent | Isolates verbose discovery from the main context. |
/compact | Reduces context bloat mid-session. |
10. Session Lifecycle
| Command / Scenario | Behavior |
|---|---|
--resume <session-id> | Continue a prior session with its context. |
--fork-session | Branch from a shared baseline to compare approaches. |
| Stale Tool Results | Start a fresh session and inject a summary rather than resuming misleading context. |
/memory | Shows which memory files are currently loaded. |
11. Skill Frontmatter Keys
| Key / Location | Effect |
|---|---|
context: fork | Runs the skill in an isolated sub-agent context. |
allowed-tools | Restricts which tools the skill may use. |
argument-hint | Prompts the user for missing arguments. |
.claude/commands/ vs ~/.claude/commands/ | Team-shared slash commands vs personal slash commands. |
.claude/rules/ + paths: | Rules files use a paths: glob list to load conditionally. |
12. Repository & Workflow Governance
| Governance Area | Rule |
|---|---|
CLAUDE.md Hierarchy | User (~/.claude/CLAUDE.md) → Project (root/CLAUDE.md) → Directory (subdir/CLAUDE.md). Directory-level files override project-level files. |
| Path-Scoped Rules | Located in .claude/rules/ using glob patterns such as **/*.test.tsx to load conventions only when matching files are edited. |
| Progressive Disclosure | Three-level skill structure: YAML frontmatter for trigger conditions, SKILL.md body for actionable steps, linked files for deep reference docs. |
| Session State | Resume if context is valid; fork to compare divergent what-if approaches; fresh start if context is stale or misleading. |
13. Escalation Triggers
| Trigger | Rule |
|---|---|
| Explicit Customer Request | Escalate immediately. |
| Policy Gap or Silence | Escalate; do not improvise policy. |
| No Meaningful Progress | Escalate rather than looping. |
| Sentiment / Self-Confidence | REJECT customer sentiment and the agent's self-reported confidence as escalation triggers. |
| Multiple Identity Matches | Ask for another identifier rather than guessing. |
14. Reliability & Evaluation Checklist
| Checklist Item | Why It Matters |
|---|---|
| Case Facts Pattern | Place non-negotiable transactional data, such as Max Budget, in a persistent block outside summarized history; it is re-injected every prompt and survives summarization. |
| Stratified Random Sampling | Measure error rates across document or prospect segments, such as small startups versus large firms, so aggregate accuracy does not mask a weak segment. |
| Independent Review Instance | Final outputs should be audited by a fresh Claude session isolated from the generator's reasoning bias. |
| Information Provenance | Require subagents to output structured claim-source mappings, including URLs, excerpts, and dates, for downstream synthesis. |