A portable, evidence-based audit you can run against any Claude Code project to get recommendations specific to that project — not generic best-practice advice.
Claude Code best-practice content is scattered across vendor docs, interviews, blogs, and community repos. Two problems follow:
- Trust — a recommendation from the Claude Code creator and a recommendation from a random blog post both read as "best practice." You cannot tell which to act on without doing the triage yourself.
- Applicability — advice that is load-bearing for an agent-heavy data pipeline is noise for a static site generator. Generic best-practice lists waste attention; project-specific recommendations do not.
This project solves both by pairing an evidence-tier system (every source and claim labelled A/B/C — so authority is visible, not asserted) with an adaptive routing audit: one copy-paste prompt that inspects your repo and conditionally fetches only the 4–8 of 42 analysis docs that match what it found. Every recommendation cites signal + source + tier, so you can verify or ignore it.
| Capability | Why It Matters | Where Else? |
|---|---|---|
| Adaptive routing audit (signal → 4–8 docs of 42) | Your project's context determines which advice you get | Nowhere |
| Evidence tier system (A–D source + 1–5 claim strength) | Know which advice to trust | Nowhere |
| Quantified behavioral insights (80% CLAUDE.md adherence, 60% context threshold) | Calibrate expectations from data, not vibes | Scattered across interviews |
| Comparative analysis (MCP vs Skills economics, orchestration approaches) | Make informed architectural decisions | Nowhere as analysis |
| Model-migration diagnostics (Opus 4.6 → 4.7 silent no-op risks) | Catch prompts that break on the version you ship | Not systematically |
| Security analysis (OWASP MCP Top 10, auto mode classifier, sandboxing) | Understand real security boundaries | OWASP (raw), not Claude-specific |
Every recommendation from the audit cites its source doc, evidence tier, and the project signal that triggered the match:
**Migrate implicit subagent dispatch in `.claude/agents/builder.md:14`**
- Signal: `model-version-4-7` (settings.json references `claude-opus-4-7`)
- Source: `analysis/model-migration-anti-patterns.md` (evidence-tier: Mixed)
- Action: Replace "Dispatch the work to available subagents" with
"Use the Explore subagent to scan src/, then the Plan subagent to design the change."If you cannot verify a recommendation against the cited doc, the audit failed — that is the design.
- Practitioners with a specific repo: run the one-prompt audit; get 4–8 cited recommendations scoped to your project rather than 42 docs to read.
- Evaluators weighing claims from any AI tooling source: the evidence-tier system (A–D source quality + 1–5 claim strength) applies to any claim, not just claims in this repo.
- Teams standardizing practice across multiple Claude Code projects: the audit output is structured and comparable — diff two repos' audits to surface drift.
- Not a tooling library. See everything-claude-code (119K+ stars, 125+ skills, 28+ agents) for batteries-included tooling.
- Not a methodology framework. See superpowers for disciplined workflow patterns (TDD enforcement, systematic debugging).
- Not implementation how-to. If a recommendation says "add a PreToolUse hook," this project explains why and when; it does not paste the hook code. Pair this project with the two above — use alongside, not instead of.
Copy-paste this into Claude Code in any project. It collects signals, fetches the routing map, and conditionally fetches 4–8 of the 42 analysis docs based on what it observes. One prompt; 6–10 network fetches; 1–5 minutes typical round-trip.
Audit this project with the adaptive routing protocol at
https://raw.githubusercontent.com/flying-coyote/claude-code-project-best-practices/master/AUDIT-CONTEXT.md
1. WebFetch AUDIT-CONTEXT.md. Run every command in its "Signal Collection Commands" section.
2. For each Signal row whose condition your output matches, queue the listed docs. Add the three "Always Fetch" docs unconditionally. Apply the Anti-Bloat Rule (drop to ≤8 signal-triggered fetches).
3. WebFetch each queued doc from https://raw.githubusercontent.com/flying-coyote/claude-code-project-best-practices/master/{path}.
4. Produce the audit using the output format in ONE-LINE-PROMPT.md. Every recommendation must cite signal key, source doc, and evidence-tier (read from YAML frontmatter, not prose). Edge cases (no .claude/, bare repo, missing claude-doctor, no model field): handle silently per ONE-LINE-PROMPT.md "EDGE CASES" block.
See ONE-LINE-PROMPT.md for the full output format, worked-example recommendation, edge-case handling, and customization flags.
| You are... | Start with... | Then... |
|---|---|---|
| An external practitioner with a specific project | The Quick Start audit above | Follow the 4–8 cited docs the audit returns |
| Evaluating a claim from any AI tooling source | analysis/evidence-tiers.md |
The dual-tier system (A–D source + 1–5 claim strength) applies broadly |
| Choosing a tool or framework | analysis/tool-ecosystem.md + analysis/framework-selection-guide.md |
Narrow via the specific decision doc |
| Contributing an analysis doc | CONTRIBUTING.md → Integration Checklist |
Start from analysis/CANONICAL-DOC-TEMPLATE.md |
The analysis/ directory contains 43 .md files: these 42 routable analysis docs plus CANONICAL-DOC-TEMPLATE.md, a non-routable template excluded from the count.
| Document | What It Covers |
|---|---|
| evidence-tiers.md | Dual-tier classification system for evaluating claims |
| behavioral-insights.md | Quantified Claude Code behavior: context thresholds, instruction adherence, prompt sensitivity across model versions |
| model-migration-anti-patterns.md | Six prompt anti-patterns that break on Opus 4.7; cross-version diagnostic matrix |
| harness-engineering.md | Harness philosophy, diagnostic framework, infrastructure patterns |
| scheduled-and-looping-primitives.md | Unattended execution: /loop, /goal, Routines, Desktop scheduled tasks, the Ralph lineage, and the "loop engineering" framing (EMERGING) |
| claude-md-progressive-disclosure.md | 3-tier CLAUDE.md evolution across 6 repos, ~150 instruction budget |
| agent-driven-development.md | Agent-driven methodology with 7-repo quantified evidence |
| agent-principles.md | 6 production reliability principles |
| agent-evaluation.md | Eval methodology from Anthropic engineering |
| orchestration-comparison.md | When to use native subagents vs GSD vs CAII vs agent teams |
| framework-selection-guide.md | Orchestration framework decision matrix |
| mcp-patterns.md | 7 failure modes + OWASP security mapping |
| mcp-vs-skills-economics.md | Cost/performance analysis: Skills 50% cheaper than MCP |
| mcp-daily-essentials.md | Optimal plugin/MCP configuration (4 plugins + 2 MCPs) |
| mcp-client-integration.md | Two MCP server architectures compared |
| plugins-and-extensions.md | Skills vs MCP vs Hooks vs Commands decision framework |
| safety-and-sandboxing.md | 4-layer security stack, auto mode analysis, sandbox architecture |
| secure-code-generation.md | OWASP-aware code generation patterns |
| tool-ecosystem.md | Claude Code vs alternatives + Specification Gap framework |
| domain-knowledge-architecture.md | Domain knowledge encoding for LLM-assisted development |
| memory-system-patterns.md | Auto-memory sizing by project type, 4 memory types, staleness patterns |
| memory-systems-archetype-recommendations.md | Index across 7 memory-system archetypes (curated KB, code monorepo, second brain, cross-project portfolio, work-state tracker, session archive, team-shared memory) |
| memory-systems-recommendation-methodology.md | Methodology + self-critique behind the archetype recommendations: scale thresholds (200/500/6k), 8 challengeable assumptions, evidence discipline |
| memory-systems-archetype-a-curated-kb.md | Archetype A — curated analytical knowledge bases (Karpathy LLM Wiki paradigm, graphify+footer, Lum1104 alternative) |
| memory-systems-archetype-b-code-monorepo.md | Archetype B — code-heavy monorepos (Tree-sitter AST + community detection) |
| memory-systems-archetype-c-personal-second-brain.md | Archetype C — personal cross-domain second brains |
| memory-systems-archetype-c-egress-constrained.md | Archetype C-EC — egress-constrained corpora (no LLM egress; wikilinks + grep + local graph) |
| memory-systems-archetype-d-cross-project-portfolio.md | Archetype D — cross-project portfolios with federation |
| memory-systems-archetype-e-work-state-tracker.md | Archetype E — work-state trackers with temporal discipline |
| memory-systems-archetype-f-session-archive.md | Archetype F — session-history mining and transcript adapters |
| memory-systems-archetype-g-team-shared-memory.md | Archetype G — team-shared memory with multi-tool concurrency |
| memory-systems-graphify-vs-understand-anything.md | A/B comparison of two LLM-driven graph-builders + ~25% EXTRACTED-edge hallucination spot-check finding |
| memory-systems-genealogy-baseline.md | Empirical 3-corpus baseline — unaugmented stack scored 8/9 DEFINITIVE; routing + dedicated memory files outweigh graph augmentation |
| session-quality-tools.md | claude-doctor signal reliability + gap statements — RETIRING, defers to first-party /insights for session-pattern analysis |
| confidence-scoring.md | HIGH/MEDIUM/LOW assessment framework |
| evidence-based-revalidation.md | Hypothesis confidence tracking, revalidation before demos |
| local-cloud-llm-orchestration.md | Hybrid MLX+Claude architecture, tokenization boundary, hallucination scrubbing |
| dapr-durable-agents.md | Agent infrastructure-as-runtime (Dapr) — durability, SPIFFE identity, OTel, LLM abstraction; complementary to MCP |
| federated-query-architecture.md | 15/15 benchmark queries, 86–99% cost savings, TCO calculator |
| automated-config-assessment.md | Baseline-deviation-remediation pattern, 3,816+ sensors, 100% detection |
| security-data-pipeline.md | Zeek → OCSF → Parquet → Iceberg pipeline, 30K records/sec |
| cross-project-synchronization.md | Cross-repo dependency cascading, 4-phase enrichment cascade |
| Document | Purpose |
|---|---|
| AUDIT-CONTEXT.md | Signal → advisory routing map (the audit's core mechanism) |
| ONE-LINE-PROMPT.md | Full prompt + output format + edge cases |
| SOURCES.md | Comprehensive source database with evidence tiers |
| SOURCES-QUICK-REFERENCE.md | Top 30 authority-weighted sources |
| analysis/CANONICAL-DOC-TEMPLATE.md | Template for new analysis docs; canonical frontmatter schema |
| DECISIONS.md | Architecture decision records |
| CONTRIBUTING.md | Contribution guide + integration checklist |
| PLAN.md | Current priorities and recent activity |
- CLAUDE.md is followed ~80% of the time — use hooks for 100% enforcement (Boris Cherny, March 2026).
- Context quality degrades at 60% capacity, not when full — proactive intervention saves quality.
- Opus 4.7 interprets prompts literally — 4.6-tuned prompts with vague descriptors, edge-case gestures, or unanchored triggers may silently no-op (Anthropic migration guide, April 2026).
- Skills are 50% cheaper than equivalent MCP — but MCP offers better isolation (Tenzir).
- Auto mode approves 93% of tool calls — viable for most workflows (Anthropic, March 2026).
- Custom subagents can "gatekeep context" — prefer native delegation unless truly specialized (Boris Cherny).
- Agent-driven repos achieve 95–100% co-authoring with full harness infrastructure (7-repo portfolio).
- PreToolUse hooks enforce ~100% vs ~80% for CLAUDE.md alone — hooks are the security boundary, not instructions.
- Federated query saves 86–99% vs centralized — zeek-iceberg-demo: 0.19s vs 27.52s for equivalent queries.
- CLAUDE.md follows 3-tier progressive disclosure — 42–57 lines (minimal) → 99–112 (resource map) → 166–209 (rules + security) across 6 repos.
- "Loop engineering" is the orchestration face of harness engineering, not a new paradigm — Boris Cherny's "I write loops" (WorkOS, June 2026) productized as
/loop//goal/Routines; the term was coined by Addy Osmani, not Cherny. Delegation is still narrow — developers fully delegate only 0–20% of tasks (Anthropic 2026 Agentic Coding Trends Report).
| Source | Key Contribution |
|---|---|
| Boris Cherny (Claude Code creator) | Quantified behavioral insights, five-layer architecture |
| Anthropic Engineering Blog | Auto mode, agent skills, hooks reference, eval methodology, Opus 4.7 migration guide |
| OWASP MCP Top 10 | MCP security framework |
| 7-Repo Portfolio Analysis | Agent-driven development evidence, infrastructure maturity, cross-repo coordination |
| Source | Key Contribution |
|---|---|
| Nate B. Jones | Agent principles, Specification Gap, OB1 memory architecture |
| IndyDevDan | Trust-based engineering, hooks mastery, agent-scoped patterns |
| Simon Willison | Opus 4.7 system-prompt analysis (selective-literalism counter-signal) |
| everything-claude-code | Comprehensive tooling reference (119K stars) |
| superpowers | Disciplined methodology, anti-rationalization |
Full database: SOURCES.md.
v2.1 — 42 analysis documents with production evidence from a 7-repo portfolio, covering agent-driven development, security data pipelines, federated query architecture, cross-project synchronization, session quality diagnostics, Opus 4.8 migration readiness (with a volatile Fable 5 / Mythos 5 currency note), unattended-execution primitives (/loop, /goal, Routines, scheduled tasks) plus the "loop engineering" framing, and 7 memory-system archetypes (curated KB through team-shared memory) with empirical Pass-2 testbed findings on this repo (graphify vs understand-anything A/B + ~25% EXTRACTED-edge hallucination spot-check).
Archive: Prior v1 patterns (24 docs) live in archive/patterns-v1/ — preserved for historical comparison, not active guidance. See ARCHIVE.md.
Contributions welcome, especially: evidence-based analysis of new claims, quantified behavioral observations, comparative evaluations, and source verification.
Adding a new analysis doc? Follow the Integration Checklist in CONTRIBUTING.md — updates are coordinated across SOURCES.md, AUDIT-CONTEXT.md (routing), README.md (this file's table), and INDEX.md. Start from the CANONICAL-DOC-TEMPLATE.md.
MIT License — use freely, attribution appreciated.