From b65630641b363d6bda5679ee702b04516ed80ba9 Mon Sep 17 00:00:00 2001 From: Florian BRUNIAUX Date: Tue, 10 Mar 2026 08:35:13 +0100 Subject: [PATCH] refactor(guide): restructure guide/ into thematic subdirectories Reorganize 22 guide files from a flat directory into 5 thematic subdirs: - core/ (architecture, methodologies, known-issues, claude-code-releases, visual-reference) - security/ (security-hardening, sandbox-isolation, sandbox-native, production-safety, data-privacy) - ecosystem/ (ai-ecosystem, mcp-servers-ecosystem, third-party-tools, remarkable-ai) - roles/ (ai-roles, adoption-approaches, learning-with-ai, agent-evaluation) - ops/ (devops-sre, observability, ai-traceability) All internal links updated across ~50 files (ultimate-guide.md, workflows/, diagrams/, README.md, docs/, tools/, examples/, machine-readable/). Also: merge search-tools-cheatsheet.md into cheatsheet.md, rewrite guide/README.md with H2 grouped sections, update CLAUDE.md repository structure. Co-Authored-By: Claude Sonnet 4.6 --- CHANGELOG.md | 234 ++++++------- CLAUDE.md | 15 +- IDEAS.md | 4 +- README.md | 80 ++--- docs/for-cto.md | 2 +- docs/for-tech-leads.md | 2 +- guide/README.md | 111 ++++-- guide/cheatsheet.md | 20 +- guide/{ => core}/architecture.md | 4 +- guide/{ => core}/claude-code-releases.md | 0 guide/{ => core}/known-issues.md | 0 guide/{ => core}/methodologies.md | 0 guide/{ => core}/visual-reference.md | 16 +- guide/diagrams/01-foundations.md | 20 +- guide/diagrams/02-context-and-sessions.md | 4 +- guide/diagrams/03-configuration-system.md | 2 +- guide/diagrams/04-architecture-internals.md | 52 +-- guide/diagrams/05-mcp-ecosystem.md | 6 +- guide/diagrams/08-security-and-production.md | 82 ++--- guide/diagrams/10-adoption-and-learning.md | 44 +-- guide/diagrams/README.md | 4 +- guide/{ => ecosystem}/ai-ecosystem.md | 2 +- .../{ => ecosystem}/mcp-servers-ecosystem.md | 2 +- guide/{ => ecosystem}/remarkable-ai.md | 0 guide/{ => ecosystem}/third-party-tools.md | 12 +- guide/{ => ops}/ai-traceability.md | 6 +- guide/{ => ops}/devops-sre.md | 6 +- guide/{ => ops}/observability.md | 4 +- guide/{ => roles}/adoption-approaches.md | 0 guide/{ => roles}/agent-evaluation.md | 4 +- guide/{ => roles}/ai-roles.md | 8 +- guide/{ => roles}/learning-with-ai.md | 8 +- guide/search-tools-cheatsheet.md | 119 ------- guide/{ => security}/data-privacy.md | 0 guide/{ => security}/production-safety.md | 2 +- guide/{ => security}/sandbox-isolation.md | 4 +- guide/{ => security}/sandbox-native.md | 2 +- guide/{ => security}/security-hardening.md | 4 +- guide/ultimate-guide.md | 60 ++-- guide/workflows/agent-teams.md | 4 +- guide/workflows/iterative-refinement.md | 2 +- guide/workflows/search-tools-mastery.md | 2 +- guide/workflows/spec-first.md | 2 +- guide/workflows/tdd-with-claude.md | 2 +- machine-readable/reference.yaml | 324 +++++++++--------- mcp-server/content/reference.yaml | 322 ++++++++--------- tools/audit-prompt.md | 2 +- tools/onboarding-prompt.md | 2 +- 48 files changed, 772 insertions(+), 835 deletions(-) rename guide/{ => core}/architecture.md (99%) rename guide/{ => core}/claude-code-releases.md (100%) rename guide/{ => core}/known-issues.md (100%) rename guide/{ => core}/methodologies.md (100%) rename guide/{ => core}/visual-reference.md (98%) rename guide/{ => ecosystem}/ai-ecosystem.md (99%) rename guide/{ => ecosystem}/mcp-servers-ecosystem.md (99%) rename guide/{ => ecosystem}/remarkable-ai.md (100%) rename guide/{ => ecosystem}/third-party-tools.md (98%) rename guide/{ => ops}/ai-traceability.md (98%) rename guide/{ => ops}/devops-sre.md (98%) rename guide/{ => ops}/observability.md (99%) rename guide/{ => roles}/adoption-approaches.md (100%) rename guide/{ => roles}/agent-evaluation.md (98%) rename guide/{ => roles}/ai-roles.md (98%) rename guide/{ => roles}/learning-with-ai.md (99%) delete mode 100644 guide/search-tools-cheatsheet.md rename guide/{ => security}/data-privacy.md (100%) rename guide/{ => security}/production-safety.md (99%) rename guide/{ => security}/sandbox-isolation.md (99%) rename guide/{ => security}/sandbox-native.md (99%) rename guide/{ => security}/security-hardening.md (99%) diff --git a/CHANGELOG.md b/CHANGELOG.md index 928be4f..298ad37 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -30,7 +30,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Claude Code Security note enriched §7.4** (`guide/ultimate-guide.md`) — added Mozilla Firefox validation context (March 2026): Opus 4.6 scanned ~6,000 C++ files in Firefox's JS engine, surfaced 22 confirmed vulnerabilities (14 high severity) in two weeks. Reinforces the "limited research preview" note with production evidence. -- **Pipelex + MTHDS added** (`guide/third-party-tools.md`) — new entry in "External Orchestration Frameworks" for Pipelex, Python runtime of the open MTHDS standard. Declarative DSL (`.mthds` files) for creating typed, git-versionable, multi-LLM AI methods. Integrates natively with Claude Code via `/plugin marketplace add mthds-ai/skills`. 623 stars (MIT, created May 2025). Status "Watch" — MTHDS standard not yet validated at scale. Architectural note distinguishing Pipelex (DSL for pipelines) from Ruflo/AthenaFlow (agent orchestration). +- **Pipelex + MTHDS added** (`guide/ecosystem/third-party-tools.md`) — new entry in "External Orchestration Frameworks" for Pipelex, Python runtime of the open MTHDS standard. Declarative DSL (`.mthds` files) for creating typed, git-versionable, multi-LLM AI methods. Integrates natively with Claude Code via `/plugin marketplace add mthds-ai/skills`. 623 stars (MIT, created May 2025). Status "Watch" — MTHDS standard not yet validated at scale. Architectural note distinguishing Pipelex (DSL for pipelines) from Ruflo/AthenaFlow (agent orchestration). - **Diagrams updated — 3 files** (`guide/diagrams/`) — Mermaid diagrams updated following releases v2.1.59–v2.1.69 and documentation corrections v3.29–v3.31. (1) `02-context-and-sessions.md`: Memory Hierarchy goes from 5 to 6 types — addition of **Native Auto-Memory** (`~/.claude/projects/*/memory/MEMORY.md`, v2.1.59+) between Subdirectory CLAUDE.md and In-Conversation Context, cross-session scope, distinct green style from ephemeral types. (2) `03-configuration-system.md`: Hooks Event Pipeline enriched with 3 new events — `InstructionsLoaded` (v2.1.69+, session start), `UserPromptSubmit` (before PreToolUse, exit 2 = feedback), `Stop / SessionEnd` (renamed) — and a note on the HTTP type (POST JSON, v2.1.63+). (3) `05-mcp-ecosystem.md`: Official Servers goes from 3 to 5 entries — added `git-mcp` (official Anthropic, 12 git tools) and `github-mcp` (official GitHub, full platform). @@ -86,7 +86,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Documentation -- **Conductor section enriched** (`guide/third-party-tools.md:376`) — section rewritten from 5 generic bullets to 6 structured subsections, verified against official changelog (conductor.build). Added: workspace status system (backlog → done, v0.35.0), Next Workspace button for agent queue navigation (v0.36.4), turn-by-turn diff viewer (v0.22.0), Manual Mode built-in editor replacing VSCode for quick edits (v0.37.0), full GitHub/CI integration details (Actions tab v0.33.2, failing CI → Claude auto-fix v0.12.0, PR workflow with `⌘⇧P`), Linear deeplinks, Codex support alongside Claude, Melty Labs attribution. Community workflow pattern added: 5+ parallel features across multiple repos, BMAD + Conductor combo for spec-driven development (user-reported, unverified claim clearly marked). +- **Conductor section enriched** (`guide/ecosystem/third-party-tools.md:376`) — section rewritten from 5 generic bullets to 6 structured subsections, verified against official changelog (conductor.build). Added: workspace status system (backlog → done, v0.35.0), Next Workspace button for agent queue navigation (v0.36.4), turn-by-turn diff viewer (v0.22.0), Manual Mode built-in editor replacing VSCode for quick edits (v0.37.0), full GitHub/CI integration details (Actions tab v0.33.2, failing CI → Claude auto-fix v0.12.0, PR workflow with `⌘⇧P`), Linear deeplinks, Codex support alongside Claude, Melty Labs attribution. Community workflow pattern added: 5+ parallel features across multiple repos, BMAD + Conductor combo for spec-driven development (user-reported, unverified claim clearly marked). - **Claude Code Releases tracking**: Updated to v2.1.69 (from v2.1.66) - v2.1.69: InstructionsLoaded hook, 4 security fixes (nested skills/symlink bypass/trust dialog/sandbox), 15+ memory leak fixes, Voice STT 20 languages, ${CLAUDE_SKILL_DIR}, /reload-plugins @@ -103,15 +103,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Added -- **Entire CLI enrichment (6 sections, 4 files)** — integration of production analysis issue #802 (Méthode Aristote) into the guide. Content added: (1) `guide/ai-traceability.md` — complete "workflow without vs with Entire" diagram showing the 7 hooks and what they capture (UserPromptSubmit, PreToolUse, PostToolUse, Stop...), actual checkpoint structure (`entire/checkpoints/v1/` with metadata.json + full.jsonl + prompt.txt + context.md), orphan branch diagram (no common ancestor = zero merge conflict), Go/No-Go table with measurable thresholds (< 10 MB/session, push < 5s, < 100 MB/week) and 2h spike commands. (2) `guide/ai-ecosystem.md` — Claude → Gemini agent handoffs diagram with context preservation (reasoning trace, touched files, decisions, rejected approaches), "no cold start" explanation. (3) `guide/third-party-tools.md` — delta table vs existing setups (7-day JSONL vs permanent checkpoints, absent human/AI attribution vs % per line, silent handoffs vs auto-passed context). (4) `guide/security-hardening.md` — approval gate flow diagram (policy check → low risk auto-OK / high risk → reviewer transcript + diffs → approve/reject → immutable audit trail). Source: [github.com/methode-aristote/app/issues/802](https://github.com/methode-aristote/app/issues/802). +- **Entire CLI enrichment (6 sections, 4 files)** — integration of production analysis issue #802 (Méthode Aristote) into the guide. Content added: (1) `guide/ops/ai-traceability.md` — complete "workflow without vs with Entire" diagram showing the 7 hooks and what they capture (UserPromptSubmit, PreToolUse, PostToolUse, Stop...), actual checkpoint structure (`entire/checkpoints/v1/` with metadata.json + full.jsonl + prompt.txt + context.md), orphan branch diagram (no common ancestor = zero merge conflict), Go/No-Go table with measurable thresholds (< 10 MB/session, push < 5s, < 100 MB/week) and 2h spike commands. (2) `guide/ecosystem/ai-ecosystem.md` — Claude → Gemini agent handoffs diagram with context preservation (reasoning trace, touched files, decisions, rejected approaches), "no cold start" explanation. (3) `guide/ecosystem/third-party-tools.md` — delta table vs existing setups (7-day JSONL vs permanent checkpoints, absent human/AI attribution vs % per line, silent handoffs vs auto-passed context). (4) `guide/security/security-hardening.md` — approval gate flow diagram (policy check → low risk auto-OK / high risk → reviewer transcript + diffs → approve/reject → immutable audit trail). Source: [github.com/methode-aristote/app/issues/802](https://github.com/methode-aristote/app/issues/802). - **`issue-triage` skill** (`examples/skills/issue-triage/`) — 3-phase issue backlog management for maintainers: automated audit of all open issues (categorization, Jaccard duplicate detection against open + 20 recent closed, risk classification Red/Yellow/Green, staleness 30/90-day thresholds, cross-reference to open PRs), opt-in deep analysis via parallel agents (full body + comments, duplicate verification, missing-info detection, effort estimate), and validated triage actions with mandatory `AskUserQuestion` gate (comment / label / close with close-reason). Jaccard algorithm is self-contained at runtime (no external library: normalize → tokenize → set intersection/union → threshold 0.60). Cross-referenced with `/pr-triage` for PR-side backlog management. - **`pr-triage` skill** (`examples/skills/pr-triage/`) — 3-phase PR backlog management for maintainers: automated audit of all open PRs (size classification, overlap detection, cluster analysis, staleness, CI status, PR-issue linking), opt-in deep review via parallel `code-reviewer` agents, and validated comment posting with mandatory `AskUserQuestion` gate. Stack-agnostic (Node/TS, Python, Rust, Go checklists included), cross-platform clipboard (pbcopy/xclip/wl-copy/clip.exe), and cross-referenced with `/review-pr` for single-PR use cases. -- **External Orchestration Frameworks** (`guide/third-party-tools.md`, new section) — new category architecturally distinct from existing multi-instance tools (Gas Town, multiclaude). Documented distinction: launching multiple Claude Code instances in parallel vs. replacing/augmenting the internal orchestration layer with a full runtime. Two tools covered: (1) **Ruflo** (formerly claude-flow, 18.9k stars) — most adopted framework, hierarchical queen + workers swarms, 60+ specialized agents, Q-Learning router, 42+ skills, 17 hooks, SQLite persistence. Install recommendation via `npx ruflo@latest` (not curl|bash). Performance claims (84.8% SWE-Bench, 352x WASM) marked unverified, ongoing rebrand documented. (2) **Athena Flow** — different architecture (hooks → UDS → NDJSON → Node.js runtime → TUI), intercepts hook events rather than augmenting the agent layer. First workflow: autonomous Playwright E2E test builder. Status "Watch — not recommended yet" (project too recent, source audit missing). Complete evaluations: `docs/resource-evaluations/073-athena-flow-workflow-runtime.md` (2/5 Watch) and `074-ruflo-multi-agent-orchestration.md` (3/5 Pertinent). +- **External Orchestration Frameworks** (`guide/ecosystem/third-party-tools.md`, new section) — new category architecturally distinct from existing multi-instance tools (Gas Town, multiclaude). Documented distinction: launching multiple Claude Code instances in parallel vs. replacing/augmenting the internal orchestration layer with a full runtime. Two tools covered: (1) **Ruflo** (formerly claude-flow, 18.9k stars) — most adopted framework, hierarchical queen + workers swarms, 60+ specialized agents, Q-Learning router, 42+ skills, 17 hooks, SQLite persistence. Install recommendation via `npx ruflo@latest` (not curl|bash). Performance claims (84.8% SWE-Bench, 352x WASM) marked unverified, ongoing rebrand documented. (2) **Athena Flow** — different architecture (hooks → UDS → NDJSON → Node.js runtime → TUI), intercepts hook events rather than augmenting the agent layer. First workflow: autonomous Playwright E2E test builder. Status "Watch — not recommended yet" (project too recent, source audit missing). Complete evaluations: `docs/resource-evaluations/073-athena-flow-workflow-runtime.md` (2/5 Watch) and `074-ruflo-multi-agent-orchestration.md` (3/5 Pertinent). -- **For Tech Leads & Engineering Managers** (`guide/learning-with-ai.md`, new §12) — dedicated section for tech leads and engineering managers, a blind spot identified through resource evaluation (Mathieu Eveillard, "Génération LLM"). The guide only covered the individual perspective; this section addresses organizational responsibility. Content: 4-week onboarding model (week 1 without AI for calibration before the tool masks gaps, validated by Create Future 2025: structured training → 14-42% → 35-65% time savings), 5 real growth metrics vs. velocity, 3 scalable mentoring models (pair rotations, 15min/week architecture hot seat, collective CLAUDE.md), AI team policy template for shared `CLAUDE.md`, 6 team-level warning signs with specific responses, quick checklist. New "Team & Organizational Research" section in sources (Create Future 2025, Stanford Digital Economy 2025, LeadDev, Stack Overflow Gen Z). Evaluation file created: `docs/resource-evaluations/2026-03-04-eveillard-generation-llm.md`. +- **For Tech Leads & Engineering Managers** (`guide/roles/learning-with-ai.md`, new §12) — dedicated section for tech leads and engineering managers, a blind spot identified through resource evaluation (Mathieu Eveillard, "Génération LLM"). The guide only covered the individual perspective; this section addresses organizational responsibility. Content: 4-week onboarding model (week 1 without AI for calibration before the tool masks gaps, validated by Create Future 2025: structured training → 14-42% → 35-65% time savings), 5 real growth metrics vs. velocity, 3 scalable mentoring models (pair rotations, 15min/week architecture hot seat, collective CLAUDE.md), AI team policy template for shared `CLAUDE.md`, 6 team-level warning signs with specific responses, quick checklist. New "Team & Organizational Research" section in sources (Create Future 2025, Stanford Digital Economy 2025, LeadDev, Stack Overflow Gen Z). Evaluation file created: `docs/resource-evaluations/2026-03-04-eveillard-generation-llm.md`. - **Compound Engineering patterns** (`guide/ultimate-guide.md`, 4 insertions) — portable patterns from Every.to's compound-engineering plugin (Kieran Klaassen, prod-tested on Cora), previously absent from the guide. (1) **Named Perspective Agents**: distinction between persona roleplay (anti-pattern, prohibited §3.x) and named perspective (DHH = fat models + thin controllers + pragmatic REST condensed into one token), with caveat on drift between Claude versions. (2) **Swarm vs Sequential**: comparison table of the two multi-agent coordination modes, decision rule (Swarm = independent + thoroughness, Teams = sequential dependencies). (3) **Skill Quality Gates**: 9-criteria checklist going beyond frontmatter validation (`/audit-agents-skills`). (4) **Brainstorm-before-planning + documentary hierarchy**: `docs/brainstorms/ → docs/plans/` workflow before coding, table of 5 directories with their distinct roles (CLAUDE.md = rules, solutions/ = solved problems, brainstorms/ = thinking, plans/ = active plans, todos/ = ephemeral tasks). Formal evaluation: `docs/resource-evaluations/2026-03-04-compound-engineering-every-to.md` (4/5 HIGH VALUE). @@ -119,7 +119,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Design Reference File pattern** (`examples/claude-md/design-reference-file.md`) — field pattern from Boris Paillard / mixt.care evaluation (March 2026). Principle: keep `brand-book.html` and `ui-kit.html` at the project root as permanent context files — Claude Code reads them before any UI generation, ensuring design system consistency across sessions without re-prompting. Content: CLAUDE.md activation snippet, 4 complete prompts (brand-book with integrated WCAG, Tailwind ui-kit, WCAG 2.1 color audit + color blindness simulation, vanilla JS Intersection Observer scroll animations), palette example with CSS semantic roles (mixt.care), WCAG correction notes (e.g. copper #B87333 fails for normal text → fix to #9B5F20). Evaluation: `docs/resource-evaluations/075-paillard-design-system-first-website.md` (3/5). -- **Straude** (`guide/third-party-tools.md`, Token & Cost Tracking section) — complete entry for straude.com, a social dashboard for tracking Claude Code usage with leaderboard and streaks. Includes: functional description, table of data transmitted to the server (costs, tokens, models, hostname), security analysis based on direct source code inspection (`npm pack straude@0.1.9`), verdict (no malware, reservations about maturity and lack of privacy policy), `--dry-run` recommendation on first use. Complete evaluation: `docs/resource-evaluations/straude-evaluation.md`. Entries added in `machine-readable/reference.yaml`. +- **Straude** (`guide/ecosystem/third-party-tools.md`, Token & Cost Tracking section) — complete entry for straude.com, a social dashboard for tracking Claude Code usage with leaderboard and streaks. Includes: functional description, table of data transmitted to the server (costs, tokens, models, hostname), security analysis based on direct source code inspection (`npm pack straude@0.1.9`), verdict (no malware, reservations about maturity and lack of privacy policy), `--dry-run` recommendation on first use. Complete evaluation: `docs/resource-evaluations/straude-evaluation.md`. Entries added in `machine-readable/reference.yaml`. ## [3.30.1] - 2026-03-04 @@ -190,11 +190,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Tool comparison table extended to 5 tools** (`guide/ultimate-guide.md` §Migration from Other Tools) — added Windsurf and Zed, fixed Cursor pricing. - **Subscription quotas: "Claude Code prompts / 5h" column** (`guide/ultimate-guide.md` §Subscription Plans & Limits) — Pro ~10-40, Max 5x ~50-200, Max 20x ~200-800. - **Resource evaluation: benchmark AI coding tools Feb 2026** (`docs/resource-evaluations/benchmark-ai-coding-tools-feb2026.md`) — score 3/5, 2 items integrated. -- **Claude Code v2.1.63 release tracking** — `machine-readable/claude-code-releases.yaml` + `guide/claude-code-releases.md`: v2.1.61–v2.1.63 (HTTP hooks, worktree config sharing, `/simplify` + `/batch`, `ENABLE_CLAUDEAI_MCP_SERVERS`). +- **Claude Code v2.1.63 release tracking** — `machine-readable/claude-code-releases.yaml` + `guide/core/claude-code-releases.md`: v2.1.61–v2.1.63 (HTTP hooks, worktree config sharing, `/simplify` + `/batch`, `ENABLE_CLAUDEAI_MCP_SERVERS`). - **HTTP hooks documentation** (`guide/ultimate-guide.md` §7.2) — `"http"` type (v2.1.63+): POST JSON → JSON response, config example with `allowedEnvVars`. - **Resource evaluation W09-2026** (`docs/resource-evaluations/weekly-intel-2026-W09.md`) — score 4/5, 3 items integrated. - **Section 9.23 — Configuration Lifecycle & The Update Loop** (`guide/ultimate-guide.md`) — continuous improvement loop, `detect-friction.sh` script, skills lifecycle, "The Update Loop" pattern. -- **Observability: Reading for Quality, Not Just Quantity** (`guide/observability.md`) — 3 qualitative patterns with `jq` commands. +- **Observability: Reading for Quality, Not Just Quantity** (`guide/ops/observability.md`) — 3 qualitative patterns with `jq` commands. - **MCP Server: 3 new tools** — `compare_versions`, `get_threat`/`list_threats`, `search_examples` (8 → 12 tools total). - **Terminal Personalization Settings** (`guide/ultimate-guide.md` §3.3) — `spinnerVerbs`, `spinnerTipsOverride`, complete example `examples/config/settings-personalization.json`. @@ -206,14 +206,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Resource evaluation: benchmark AI coding tools Feb 2026** (`docs/resource-evaluations/benchmark-ai-coding-tools-feb2026.md`) — evaluation of a comparative 5-tool benchmark (Claude Code, Cursor, Windsurf, Zed, Copilot Workspace), text copied without source URL. Score 3/5 (relevant, selective integration). 2 net items integrated: prompts/5h quotas + comparison table extension. 4 recommendations rejected (already covered). -- **Claude Code v2.1.63 release tracking** — `machine-readable/claude-code-releases.yaml` + `guide/claude-code-releases.md` updated with v2.1.61, v2.1.62, v2.1.63 (HTTP hooks, worktree config sharing, `/simplify` + `/batch` bundled commands, `ENABLE_CLAUDEAI_MCP_SERVERS` env var, wave of memory leak fixes) +- **Claude Code v2.1.63 release tracking** — `machine-readable/claude-code-releases.yaml` + `guide/core/claude-code-releases.md` updated with v2.1.61, v2.1.62, v2.1.63 (HTTP hooks, worktree config sharing, `/simplify` + `/batch` bundled commands, `ENABLE_CLAUDEAI_MCP_SERVERS` env var, wave of memory leak fixes) - **HTTP hooks documentation** (`guide/ultimate-guide.md` §7.2 Creating Hooks) — new hook type `"http"` (v2.1.63+): POST JSON to a URL, receives JSON in return. Added to the Configuration Fields table, descriptive bullet point, and complete config example with `allowedEnvVars` - **Resource evaluation W09-2026** (`docs/resource-evaluations/weekly-intel-2026-W09.md`) — evaluation of the Anthropic/Claude Code weekly watch report (Feb 24 – Mar 1, 2026): score 4/5, 3 items integrated (v2.1.63 releases, HTTP hooks, Haiku 3 deadline note already present), 3 items rejected (Cowork, DoW, Vercept) - **Section 9.23 — Configuration Lifecycle & The Update Loop** (`guide/ultimate-guide.md`) — continuous improvement loop for Claude Code configurations: friction detection from JSONL logs (`detect-friction.sh` script), skills lifecycle management (semantic versioning, deprecation, CI staleness check GitHub Actions), "The Update Loop" pattern (observe → analyze → delta update → canary test), handoff integration, DSPy/TextGrad mentions -- **Observability: Reading for Quality, Not Just Quantity** (`guide/observability.md`) — new subsection in "Analyzing Session Data": 3 qualitative patterns (repeated reads, tool failures, high edit frequency) with ready-to-use `jq` commands, linked to §9.23 +- **Observability: Reading for Quality, Not Just Quantity** (`guide/ops/observability.md`) — new subsection in "Analyzing Session Data": 3 qualitative patterns (repeated reads, tool failures, high edit frequency) with ready-to-use `jq` commands, linked to §9.23 - **Git MCP Server + GitHub MCP Server** (`guide/ultimate-guide.md` §8.2 MCP Server Catalog) — two new servers documented in the MCP catalog: - **Git MCP Server** (official Anthropic, `mcp-server-git`): 12 tools for local Git operations (git_status, git_diff, git_commit, git_log, git_create_branch, etc.), `uvx` setup, multi-repo config, Git MCP vs Bash comparison, typical workflows. Status: early dev. @@ -281,7 +281,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - CLI flags table: `remote-control` subcommand - Slash commands table: `/remote-control`, `/rc`, `/mobile` -- **`guide/security-hardening.md`** — Part 7: Remote Control Security +- **`guide/security/security-hardening.md`** — Part 7: Remote Control Security - Architecture diagram (outbound-only HTTPS relay model) - Threat model: session URL leak, RCE surface, corporate policy, persistent exposure - Community perspective (senior dev security concerns) @@ -324,7 +324,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - Compatible with 14 AI assistants (Claude Code, Cursor, Copilot, Windsurf…) - Installation guide, workflows, usage examples -- **guide/observability.md** — Complete MLflow Tracing section (~120 lines) +- **guide/ops/observability.md** — Complete MLflow Tracing section (~120 lines) - CLI mode (zero Python) + SDK mode with API wrapping - LLM-as-judge for automatic quality regression - Exact token counts vs ~15-25% variance from hooks @@ -395,7 +395,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - Confirmed gap: no existing tool in the guide combines FTS + visual analytics (heatmaps, velocity) in a local web UI - Barriers: 4-day-old repo (created Feb 19, 2026), 49 stars at time of evaluation - Author credibility: Wes McKinney (creator of pandas) - - Integration plan: `guide/observability.md` External Monitoring Tools section + mention in `guide/third-party-tools.md` + - Integration plan: `guide/ops/observability.md` External Monitoring Tools section + mention in `guide/ecosystem/third-party-tools.md` - Initial score 4/5 → challenged to 3/5 (adoption not established) + placement corrected to `observability.md` - **guide/ultimate-guide.md §5.5** — New entry "Design Intelligence: UI UX Pro Max" in Community Skill Repositories @@ -454,7 +454,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - fp.dev = agent-native local-first issue tracker for Claude Code (issues as git-committable `.md`, skills `/fp-plan` `/fp-implement` `/fp-review`, diff viewer) - Real differentiator vs Tasks API: committable issues in the repo. But insufficient adoption + Apple Silicon only + partial overlap with native Tasks API - File: `docs/resource-evaluations/2026-02-22-fp-dev-issue-tracker.md` - - **Known Gap added** in `guide/third-party-tools.md`: "Agent-native issue tracking (markdown-based, git-committable)" + - **Known Gap added** in `guide/ecosystem/third-party-tools.md`: "Agent-native issue tracking (markdown-based, git-committable)" - **Watch List**: re-evaluate when GitHub stars visible + release cadence + practitioner prod write-up ## [3.28.1] - 2026-02-22 (security patch) @@ -468,7 +468,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **5 new scanning tools catalogued**: Proximity (open-source), Enkrypt AI MCP Scanner, Cisco MCP Scanner (behavioral analysis), NeuralTrust MCP Scanner, MCPScan.ai - **Defensive resource**: Anthropic Claude Code Security (AI-powered codebase scanner, launched 2026-02-21) - **4 new sources**: Lakera "Agent Skill Ecosystem" audit (4310 OpenClaw skills), Penligent AI CVE-2026-0755, Snyk mcp-run-python SSRF, THN Anthropic CC Security -- **guide/security-hardening.md** — CVE table updated with CVE-2026-0755 and mcp-run-python SSRF entries + critical warning note (no patch available) +- **guide/security/security-hardening.md** — CVE table updated with CVE-2026-0755 and mcp-run-python SSRF entries + critical warning note (no patch available) ## [3.28.1] - 2026-02-22 @@ -506,11 +506,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **guide/ultimate-guide.md — critical claude-mem gotchas** (section claude-mem) - Hooks coexistence: before/after JSON, silent overwrite risk documented - Fail-open v9.1.0+: worker down doesn't block Claude Code, restart instructions -- **guide/methodologies.md**: cross-reference to Boris Tane Pattern from Plan-First section +- **guide/core/methodologies.md**: cross-reference to Boris Tane Pattern from Plan-First section - **machine-readable/reference.yaml**: 4 new entries (`annotation_cycle_pattern`, `custom_markdown_plans`, `boris_tane_source`, `boris_tane_author`) - **docs/resource-evaluations/boris-tane-how-i-use-claude-code.md**: formal evaluation (score 4/5, fact-check, integration decision) - **docs/resource-evaluations/aristote-ai-instructions-patterns.md**: Méthode Aristote production patterns analysis (24 ai-instructions files) -- **guide/security-hardening.md — Part 4: Integration** (+104 lines) +- **guide/security/security-hardening.md — Part 4: Integration** (+104 lines) - **4.1 PR Security Review Workflow**: 3-agent pipeline (security-auditor → data flow trace → security-patcher), ready-to-use prompts - Table by change type (API endpoint, DB query, auth, file upload, third-party lib) with risk levels - Git `pre-push` hook to alert on sensitive files (auth, payment, token, session) @@ -531,7 +531,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **docs/resource-evaluations/2026-02-22-boris-cherny-worktree-tips-reddit.md**: evaluation of Boris Cherny Reddit/Twitter (Claude Code creator) — 5 worktree tips, 40.2K views - **docs/resource-evaluations/2026-02-22-guillaume-moigneu-worktree-linkedin.md**: evaluation of Guillaume Moigneu LinkedIn (Solution Architect @ Upsun) — built-in git worktree support -- **guide/observability.md — 3 new monitoring sections** (+214 lines) +- **guide/ops/observability.md — 3 new monitoring sections** (+214 lines) - **Activity Monitoring**: audit of Claude Code actions via session JSONL — which files were read, commands executed, URLs fetched. Ready-to-use `jq` queries. Table of sensitive patterns (.env, rm -rf, external WebFetch) - **External Monitoring Tools**: comparison table ccusage / claude-code-otel / Akto / MLflow / ccboard with decision guide and install examples - **Proxying Claude Code**: why Proxyman/Charles fail (Node.js ignores system proxies), 4 solutions: `NODE_EXTRA_CA_CERTS`, `ANTHROPIC_API_URL`, mitmproxy (recommended), minimal Python proxy @@ -631,7 +631,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - Concrete example: over-scoped task vs properly-sized vertical slice - Inspired by Allan Hill (Fractional CTO) — [evaluation](docs/resource-evaluations/2026-02-19-allanhillgeek-decomposition-agentic-dev.md) (3/5) -- `guide/methodologies.md`: Expanded ATDD section with agentic application +- `guide/core/methodologies.md`: Expanded ATDD section with agentic application - Added 3-step agent workflow: Gherkin → failing tests → implementation - Gherkin example for "password reset" feature - Practical note: how to pass Gherkin file to Claude Code as task contract @@ -642,7 +642,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - Multi-agent pipeline BREAK→MODEL→ACT→DEBRIEF with 6 tooled validation gates (Node.js) - "No Spec No Code" + "No Task No Commit" invariants enforced via hooks — enforcement pattern not documented in the guide - Transparent token budget per phase (~900K total) — unique concrete estimate in the ecosystem - - Mention added in `guide/methodologies.md` (SDD Tools table) and `guide/workflows/spec-first.md` (See Also) + - Mention added in `guide/core/methodologies.md` (SDD Tools table) and `guide/workflows/spec-first.md` (See Also) - Evaluation archived: `docs/resource-evaluations/sylvain-chabaud-spec-to-code-factory.md` - **New Section 3.5**: Team Configuration at Scale — Profile-Based Module Assembly pattern @@ -730,8 +730,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Changed -- `guide/learning-with-ai.md`: Added Borg et al. 2025 RCT citation in Productivity Research bibliography (revised to factual/neutral wording after technical-writer audit) -- `guide/learning-with-ai.md`: Added "On maintainability fear" note in "Why Some Teams Get Results" section — the real risks are skill atrophy and over-delegation, not downstream quality degradation +- `guide/roles/learning-with-ai.md`: Added Borg et al. 2025 RCT citation in Productivity Research bibliography (revised to factual/neutral wording after technical-writer audit) +- `guide/roles/learning-with-ai.md`: Added "On maintainability fear" note in "Why Some Teams Get Results" section — the real risks are skill atrophy and over-delegation, not downstream quality degradation - `guide/ultimate-guide.md`: Added downstream maintainability nuance blockquote in §1.7 Trust Calibration — defect rates ≠ maintenance burden (Borg et al. 2025 blind RCT) - `machine-readable/reference.yaml`: Added 4 entries — `productivity_rct_metr`, `productivity_rct_echoes`, `productivity_maintainability_empirical`, `trust_calibration_maintainability_nuance` - Landing `faq/index.astro`: Updated "How much should I trust AI-generated code?" — added maintainability nuance (HTML visible answer + JSON-LD structured data) @@ -783,12 +783,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - `test-review.md`: coverage gaps, test quality, edge cases, failure modes - `performance-review.md`: database access, memory, caching, complexity -- **AI Kill Switch & Containment Architecture** (`guide/security-hardening.md` §3.5) +- **AI Kill Switch & Containment Architecture** (`guide/security/security-hardening.md` §3.5) - Three-level kill switch mapped to Claude Code mechanisms (scoped revocation → velocity governor → global hard stop) - Ready-to-use `velocity-governor.sh` hook example (rate-limiter for runaway agents) - Regulatory context: EU AI Act (Aug 2025), CoSAI AI Incident Response Framework V1.0, governance-containment gap stats - Sources: Fortune Dec 2025, CDOTrends Jan 2026, OASIS/CoSAI Nov 2025 -- **AI-specific incident cross-reference** (`guide/devops-sre.md`) +- **AI-specific incident cross-reference** (`guide/ops/devops-sre.md`) - Added pointer from "When NOT to Use Claude" to security-hardening.md for AI incidents (prompt injection, MCP compromise, agent exfiltration) - **Git Worktree command suite** (`examples/commands/`) @@ -830,7 +830,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Added -- **Grepai MCP documentation** (`guide/mcp-servers-ecosystem.md`) +- **Grepai MCP documentation** (`guide/ecosystem/mcp-servers-ecosystem.md`) - New "Code Search & Analysis" section (~130 lines): semantic search, call graph tracing, setup guide - Privacy: fully local (Ollama + nomic-embed-text), zero data exfiltration - Token efficiency comparison: grepai 2-3K tokens vs Grep+Read 15K for same results @@ -945,7 +945,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **README**: Commands count updated 18→22, 3 new security commands listed in examples library - **CLAUDE.md**: Slash commands table updated with `/security-check`, `/security-audit`, `/update-threat-db` - **reference.yaml**: 4 new entries (security_check_command, security_audit_command, security_threat_db, security_update_threat_db) -- **Learning Guide Enhancement**: AI fatigue symptom recognition integrated into `guide/learning-with-ai.md` +- **Learning Guide Enhancement**: AI fatigue symptom recognition integrated into `guide/roles/learning-with-ai.md` - Red Flags Checklist, Productivity Reality, UVAL Protocol sections updated ### Fixed @@ -1001,7 +1001,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - Technical challenge by technical-writer agent adjusted score from 2/5 to 3/5 - All technical claims fact-checked (TypeScript 58.9%, Python 38.5%, stack verified) -- **New Guide Section**: Agent Evaluation (`guide/agent-evaluation.md`, ~3000 tokens) +- **New Guide Section**: Agent Evaluation (`guide/roles/agent-evaluation.md`, ~3000 tokens) - **Why Evaluate Agents**: Quantify quality, compare configurations, build feedback loops - **Metrics to Track**: Response quality, tool usage, performance, user satisfaction - **Implementation Patterns**: Logging hooks, unit tests, A/B testing, feedback loops @@ -1010,12 +1010,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - Addresses critical gap identified in nao evaluation - Navigation: After `guide/ultimate-guide.md` Section 4 (Agents) -- **AI Ecosystem Update**: Section 8.2 Domain-Specific Agent Frameworks (`guide/ai-ecosystem.md`) +- **AI Ecosystem Update**: Section 8.2 Domain-Specific Agent Frameworks (`guide/ecosystem/ai-ecosystem.md`) - New subsection after "Multi-Agent Orchestration Systems" - **nao (Analytics Agents)**: Database-agnostic framework with built-in evaluation - Transposable patterns: Context builder architecture, evaluation hooks, database integrations - - Links to new `guide/agent-evaluation.md` for implementation details - - Location: guide/ai-ecosystem.md lines 1612-1638 + - Links to new `guide/roles/agent-evaluation.md` for implementation details + - Location: guide/ecosystem/ai-ecosystem.md lines 1612-1638 - **Template**: Analytics Agent with Evaluation (`examples/agents/analytics-with-eval/`, 5 files) - **README.md**: Complete setup, usage, troubleshooting (production-ready) @@ -1023,7 +1023,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **hooks/post-response-metrics.sh**: Automated metrics logging (safety, performance, errors) - **eval/metrics.sh**: Analysis script for aggregating collected metrics - **eval/report-template.md**: Monthly evaluation report template - - Demonstrates patterns from `guide/agent-evaluation.md` in complete implementation + - Demonstrates patterns from `guide/roles/agent-evaluation.md` in complete implementation - Includes safety checks (destructive operations), performance monitoring, feedback loops ### Changed @@ -1084,7 +1084,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Fixed -- **Methodologies**: Added clarification note to BMAD description about role-based naming (guide/methodologies.md line 49) +- **Methodologies**: Added clarification note to BMAD description about role-based naming (guide/core/methodologies.md line 49) ## [3.23.3] - 2026-02-09 @@ -1206,7 +1206,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - Critical sandbox bypass vulnerability patched - Recommendation: **Upgrade to v2.1.34+ immediately** - Details undisclosed pending broader adoption - - Added to CVE Summary table (guide/security-hardening.md) + - Added to CVE Summary table (guide/security/security-hardening.md) ### Documentation @@ -1231,7 +1231,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - Performance benchmarks: 50-70% accuracy drop on complex tasks (1K → 32K tokens) - Research sources: Context Rot (Chroma), Beyond Prompts (UseAI), Claude Saves Tokens (Golev) - Added Lorenz's proactive thresholds: 70% warning, 85% handoff, 95% force handoff - - File: `guide/architecture.md` Section 3.2 + - File: `guide/core/architecture.md` Section 3.2 - **Context Management**: Added research-backed proactive thresholds - Replaced generic "Check context before resuming (>75%)" with specific 70%/85%/95% ladder - Added performance degradation warnings with research links @@ -1394,8 +1394,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Git MCP Server (Official) Documentation** — Integration of Anthropic's official Git MCP server addressing version control automation gap (~1600 words, scored 5/5 CRITICAL after technical-writer challenge) - - **New section: Version Control (Official Servers)** (`guide/mcp-servers-ecosystem.md:102-255`) — Comprehensive documentation covering official Git MCP server (12 tools: git_status, git_log, git_diff, git_commit, git_add, git_reset, git_branch, git_create_branch, git_checkout, git_show, git_diff_unstaged, git_diff_staged), 3 installation methods (uvx one-liner, pip, Docker), multi-repo configuration, advanced log filtering (ISO 8601, relative dates "2 weeks ago", absolute dates), context_lines parameter for token efficiency, IDE integrations (Claude Desktop, VS Code, Zed, Zencoder with one-click install buttons), quality score 8.5/10, limitations & workarounds (early development API changes, no interactive rebase/reflog/bisect) - - **Decision Matrix: Git MCP vs GitHub MCP vs Bash Tool** (`guide/mcp-servers-ecosystem.md:212-255`) — Comprehensive comparison table (11 operations: local commits, branch management, diff/log analysis, PR creation, issue management, CI/CD checks, interactive rebase, reflog recovery, git bisect, multi-tool pipelines), decision tree workflow, 7 workflow examples with justifications (feature development, commit history analysis, code review preparation, cleanup commits, recover lost commits, bug hunting, automated release flow) + - **New section: Version Control (Official Servers)** (`guide/ecosystem/mcp-servers-ecosystem.md:102-255`) — Comprehensive documentation covering official Git MCP server (12 tools: git_status, git_log, git_diff, git_commit, git_add, git_reset, git_branch, git_create_branch, git_checkout, git_show, git_diff_unstaged, git_diff_staged), 3 installation methods (uvx one-liner, pip, Docker), multi-repo configuration, advanced log filtering (ISO 8601, relative dates "2 weeks ago", absolute dates), context_lines parameter for token efficiency, IDE integrations (Claude Desktop, VS Code, Zed, Zencoder with one-click install buttons), quality score 8.5/10, limitations & workarounds (early development API changes, no interactive rebase/reflog/bisect) + - **Decision Matrix: Git MCP vs GitHub MCP vs Bash Tool** (`guide/ecosystem/mcp-servers-ecosystem.md:212-255`) — Comprehensive comparison table (11 operations: local commits, branch management, diff/log analysis, PR creation, issue management, CI/CD checks, interactive rebase, reflog recovery, git bisect, multi-tool pipelines), decision tree workflow, 7 workflow examples with justifications (feature development, commit history analysis, code review preparation, cleanup commits, recover lost commits, bug hunting, automated release flow) - **Machine-readable index** (`reference.yaml`, +11 entries) — Added: git_mcp (description), git_mcp_guide (line pointer), git_mcp_tools (12 tools list), git_mcp_install (uvx command), git_mcp_decision_matrix (line pointer), git_mcp_repo (GitHub URL), git_mcp_score (8.5/10), git_mcp_status (early development), git_mcp_advanced_filtering (date formats), git_mcp_use_cases (5 use cases); Updated: reference.yaml updated timestamp (2026-02-03) - **Gap filled**: Official Git server documentation — mentioned in official servers table (line 29) but 0% documented → 100% comprehensive with use cases/config/decision matrix; Git vs GitHub vs Bash tool clarity — confusion not addressed → decision tree + comparison table + 7 workflow examples; Multi-repo workflows — not documented → configuration example with multiple instances; Token efficiency strategies — general advice → specific git_diff context_lines parameter, structured output benefits quantified - **Impact**: Workflow automation (AI-assisted commits, branch creation, log analysis without Bash tool), Token efficiency (structured output, context_lines control vs parsing text), Cross-platform safety (MCP vs direct Bash Git commands), Multi-tool composition (Git MCP + GitHub MCP pipelines documented), Developer experience (decision tree prevents tool selection confusion) @@ -1416,9 +1416,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Added - **Native Sandboxing Comprehensive Documentation** — Integration of official Anthropic sandboxing documentation (v2.1.0+) addressing critical security gap (~1800 words missing content, scored 5/5 CRITICAL) - - **New guide: sandbox-native.md** (`guide/sandbox-native.md`, ~3000 lines) — Complete technical reference covering OS primitives (Seatbelt for macOS, bubblewrap for Linux/WSL2), filesystem isolation (read all/write CWD), network isolation (SOCKS5 proxy with domain filtering), sandbox modes (Auto-allow vs Regular permissions), escape hatch (`dangerouslyDisableSandbox`), security limitations (domain fronting, Unix sockets privilege escalation, filesystem permission escalation), open-source runtime (`@anthropic-ai/sandbox-runtime`), platform support (macOS ✅, Linux ✅, WSL2 ✅, WSL1 ❌, Windows planned), decision tree (Native vs Docker vs Cloud), configuration examples (Strict/Balanced/Development), best practices, troubleshooting - - **Enhanced: sandbox-isolation.md** (`guide/sandbox-isolation.md`, +800 lines) — Added Section 4 "Native Claude Code Sandbox" with architecture diagram, OS primitives comparison, quick start guide, configuration example, Native vs Docker decision tree, security limitations summary, deep dive reference; Updated TL;DR table (Native CC repositioned #2 with enriched details); Updated Comparison Matrix (Native CC enriched with kernel isolation, overhead, setup details); Sections renumbered (4→5 Cloud Sandboxes, 5→6 Comparison Matrix, 6→7 Safe Autonomy, 7→8 Anti-Patterns) - - **Enhanced: architecture.md** (`guide/architecture.md:523`, +80 lines) — Added Section 5.1 "Native Sandbox (v2.1.0+)" in Permission & Security Model with architecture diagram (sandbox wrapper flow), OS primitives table, isolation model (filesystem/network/process), sandbox modes, security trade-offs table (Native vs Docker), security limitations, when-to-use guide, deep dive reference + - **New guide: sandbox-native.md** (`guide/security/sandbox-native.md`, ~3000 lines) — Complete technical reference covering OS primitives (Seatbelt for macOS, bubblewrap for Linux/WSL2), filesystem isolation (read all/write CWD), network isolation (SOCKS5 proxy with domain filtering), sandbox modes (Auto-allow vs Regular permissions), escape hatch (`dangerouslyDisableSandbox`), security limitations (domain fronting, Unix sockets privilege escalation, filesystem permission escalation), open-source runtime (`@anthropic-ai/sandbox-runtime`), platform support (macOS ✅, Linux ✅, WSL2 ✅, WSL1 ❌, Windows planned), decision tree (Native vs Docker vs Cloud), configuration examples (Strict/Balanced/Development), best practices, troubleshooting + - **Enhanced: sandbox-isolation.md** (`guide/security/sandbox-isolation.md`, +800 lines) — Added Section 4 "Native Claude Code Sandbox" with architecture diagram, OS primitives comparison, quick start guide, configuration example, Native vs Docker decision tree, security limitations summary, deep dive reference; Updated TL;DR table (Native CC repositioned #2 with enriched details); Updated Comparison Matrix (Native CC enriched with kernel isolation, overhead, setup details); Sections renumbered (4→5 Cloud Sandboxes, 5→6 Comparison Matrix, 6→7 Safe Autonomy, 7→8 Anti-Patterns) + - **Enhanced: architecture.md** (`guide/core/architecture.md:523`, +80 lines) — Added Section 5.1 "Native Sandbox (v2.1.0+)" in Permission & Security Model with architecture diagram (sandbox wrapper flow), OS primitives table, isolation model (filesystem/network/process), sandbox modes, security trade-offs table (Native vs Docker), security limitations, when-to-use guide, deep dive reference - **Resource evaluation** (`docs/resource-evaluations/native-sandbox-official-docs.md`, ~600 lines) — Scored 5/5 (CRITICAL), official Anthropic documentation, gap analysis quantified (~1800 words missing), fact-check 100% (11 claims verified), technical-writer agent challenge (3/5 → 5/5 score revision), risks of non-integration documented (security incidents, adoption friction, configuration errors) - **Production templates** (3 files): - `examples/config/sandbox-native.json` — Native sandbox configuration (denylist mode, domain allowlist, denied credentials paths, excluded commands) @@ -1450,13 +1450,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Resource Evaluation: Alan Engineering "Tour Eiffel Paradigm"** (scored 5/5, CRITICAL) — Integration of paradigm shift framework from Alan Engineering team (Charles Gorintin, CTO + Maxime Le Bras, Talent Lead) validating production-scale AI transformation (`docs/resource-evaluations/alan-tour-eiffel-paradigm.md`) - **Source**: LinkedIn Newsletter "Intelligence Humaine" (Feb 2, 2026, 3,897 followers), French healthtech company (15K+ companies, 300K+ members, €500M raised, heavily regulated industry) - **Key frameworks**: (1) Eiffel Tower Principle — AI tools transform what's architecturally possible (like elevators enabled Eiffel Tower shape), not just acceleration, (2) Ralph Wiggum Programming — agentic loops where engineers become architects/editors, (3) **Verification Paradox** — 99% AI success makes human vigilance fragile for 1% errors, need automated guardrails, (4) Precision as Currency — clear spec definition (WHAT/WHERE/HOW) is new engineer superpower, (5) Ambition Scaling — pursue previously impossible goals enabled by tools - - **Production Safety Rule 7** added (`guide/production-safety.md:639-791`): "The Verification Paradox" — when AI reliability crosses 95%, shift from manual review to automated guardrails (tests, types, lints, CI/CD gates). Anti-patterns vs Better Approaches table, 3 implementation options (automated stack, verification contracts, pre-merge checklist), integration with Rules 2/3/6 - - **Practitioner Insight** added (`guide/ai-ecosystem.md:2133-2168`): Alan Engineering section after Addy Osmani, following existing format (credentials, content summary, alignment table with guide references, production-scale context). Interview mention of Stanislas Polu (Dust co-founder) citing Mirakl achievement (75% employees → agent builders) + - **Production Safety Rule 7** added (`guide/security/production-safety.md:639-791`): "The Verification Paradox" — when AI reliability crosses 95%, shift from manual review to automated guardrails (tests, types, lints, CI/CD gates). Anti-patterns vs Better Approaches table, 3 implementation options (automated stack, verification contracts, pre-merge checklist), integration with Rules 2/3/6 + - **Practitioner Insight** added (`guide/ecosystem/ai-ecosystem.md:2133-2168`): Alan Engineering section after Addy Osmani, following existing format (credentials, content summary, alignment table with guide references, production-scale context). Interview mention of Stanislas Polu (Dust co-founder) citing Mirakl achievement (75% employees → agent builders) - **Machine-readable index** updated (`reference.yaml`): Added `practitioner_alan`, `practitioner_alan_source`, `verification_paradox`, `verification_paradox_source` entries - **README.md counters harmonized**: Fixed evaluation count inconsistencies (37/35/38 → 41 across 5 locations: line 18 intro, line 74 mermaid diagram, line 118 structure, line 163 features, line 427 details) - **Challenge phase**: Technical-writer agent reviewed 6 proposed integrations, rejected 4 (Quick Start paradigm shift, Mental Model refactoring, methodologies.md deep dive, XML Prompting precision) for dilution/duplication concerns, approved 3 (production-safety, ai-ecosystem, reference.yaml) - **Language note**: Original article in French, concepts and Henri Bergson quote ("L'intelligence est la faculté de fabriquer des outils à faire des outils") translated for guide -- **Multi-IDE Configuration Sync Pattern** — Documented strategies for maintaining consistent AI instructions across multiple coding tools (Claude Code, Cursor, Copilot) in `guide/ai-ecosystem.md:1256-1329` +- **Multi-IDE Configuration Sync Pattern** — Documented strategies for maintaining consistent AI instructions across multiple coding tools (Claude Code, Cursor, Copilot) in `guide/ecosystem/ai-ecosystem.md:1256-1329` - **Problem statement**: Table comparing config files (CLAUDE.md, .cursorrules, AGENTS.md, .github/copilot-instructions.md) — without sync, each drifts independently causing inconsistent AI behavior - **Solution 1**: Native @import (recommended for Claude Code solo usage) — no build step, maintained by Anthropic, but Cursor doesn't support it - **Solution 2**: Script-based generation for multi-IDE teams — source of truth in `docs/ai-instructions/` compiled into tool-specific configs via bash/node sync scripts @@ -1466,7 +1466,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Resource Evaluation: Addy Osmani LinkedIn Post** (scored 2/5, Marginal - Tracking mention only) — Post about Anthropic study (17% comprehension gap) evaluated but not integrated due to 100% overlap with primary source already documented (`docs/resource-evaluations/addy-osmani-linkedin-anthropic-study.md`) - **Content**: LinkedIn post (Feb 1, 2026, 246K reach) citing Shen & Tamkin 2026 study on AI-assisted learning - **Key claims verified**: 17% comprehension gap, 2-minute productivity gain, "thinking partner vs code vending machine" framing - - **Overlap**: 100% with arXiv:2601.20245 already cited 3× in `guide/learning-with-ai.md` (lines 114, 868, 890) + - **Overlap**: 100% with arXiv:2601.20245 already cited 3× in `guide/roles/learning-with-ai.md` (lines 114, 868, 890) - **Decision**: Minimal integration (1-2 line tracking mention) to document mainstream diffusion timeline without content duplication - **Challenge phase**: Technical-writer agent confirmed score 2/5 content but noted 3/5 ecosystem context (authority messager + diffusion milestone) - **New criterion documented**: "Influencer Amplification" pattern for future evaluations (reach >100K + timeline awareness) @@ -1509,7 +1509,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Reference Index**: 8 new entries in `machine-readable/reference.yaml` (spec_first_workflow, spec_modular_design, spec_operational_boundaries, spec_command_template, spec_anti_monolithic, spec_osmani_source, spec_osmani_evaluation, spec_osmani_score) - **README.md**: Incremented resource evaluations count (35 → 36 assessments) - **Fresh Context Pattern**: New "Session-per-Concern Pipeline" variant — dedicates a fresh session to each quality dimension (plan → test → implement → security review → perf → code review) instead of looping the same task. References OpusPlan and TDD. (`guide/ultimate-guide.md:1595`) -- **Resource Evaluation #19: dclaude** (Patrick Debois) — Dockerized Claude Code wrapper evaluated at 2/5 (Marginal). Fills a narrow gap (Linux + Docker Engine without Docker Desktop) but uses standard containers with host Docker socket mount — weaker isolation than Docker Sandboxes' microVMs. Footnote added in `guide/sandbox-isolation.md` Limitations subsection. (`docs/resource-evaluations/dclaude-docker-wrapper.md`) +- **Resource Evaluation #19: dclaude** (Patrick Debois) — Dockerized Claude Code wrapper evaluated at 2/5 (Marginal). Fills a narrow gap (Linux + Docker Engine without Docker Desktop) but uses standard containers with host Docker socket mount — weaker isolation than Docker Sandboxes' microVMs. Footnote added in `guide/security/sandbox-isolation.md` Limitations subsection. (`docs/resource-evaluations/dclaude-docker-wrapper.md`) - **Resource Evaluation #20: 10 Tips from Inside the Claude Code Team** (paddo.dev / Boris Cherny thread) — Scored 4/5 (High Value). 4 integrations in ultimate-guide.md: - **Prompting as Provocation** (section 2.6.1): 3 challenge patterns — Gatekeeper, Proof Demand, Reset — treating Claude as a peer to convince rather than an assistant to direct (`guide/ultimate-guide.md:3029`) - **Model-as-Security-Gate** hook pattern: Route permission requests to Opus 4.5 via PreToolUse hook for intelligent security screening beyond static rules (`guide/ultimate-guide.md:6907`) @@ -1523,9 +1523,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **agentskills.io Open Standard integration** (scored 4/5) — Agent Skills follow the [agentskills.io](https://agentskills.io) specification, created by Anthropic, supported by 26+ platforms (Cursor, VS Code, GitHub, Codex, Gemini CLI, Goose, Roo Code, etc.) - SKILL.md frontmatter table now distinguishes spec fields (`name`, `description`, `allowed-tools`, `license`, `compatibility`, `metadata`) from Claude Code-only extensions (`context`, `agent`) (`guide/ultimate-guide.md:5180`) - `skills-ref validate` / `skills-ref to-prompt` CLI tool added to skill creation workflow (`guide/ultimate-guide.md:5188`) - - Skill Portability section in Goose comparison (`guide/ai-ecosystem.md:1876`) + - Skill Portability section in Goose comparison (`guide/ecosystem/ai-ecosystem.md:1876`) - 16 new reference.yaml entries (spec, CLI, anthropics/skills repo, SafeDep threat model, blog) -- **Agent Skills Supply Chain Risks** — New section 1.2 in security-hardening.md based on SafeDep threat model (8-14% of public skills have vulnerabilities). 4 mitigations: review SKILL.md, validate with skills-ref, pin versions, audit scripts/ (`guide/security-hardening.md:121`) +- **Agent Skills Supply Chain Risks** — New section 1.2 in security-hardening.md based on SafeDep threat model (8-14% of public skills have vulnerabilities). 4 mitigations: review SKILL.md, validate with skills-ref, pin versions, audit scripts/ (`guide/security/security-hardening.md:121`) - **anthropics/skills** (60K+⭐) added to README Complementary Resources table - **Resource Evaluations**: Skill Doctor GitHub Action (2/5, marginal), agentskills.io specification (4/5, high value) (`docs/resource-evaluations/skill-doctor-github-action.md`, `docs/resource-evaluations/agentskills-io-specification.md`) @@ -1611,7 +1611,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). --- -- **Sandbox Isolation for Coding Agents** — `guide/sandbox-isolation.md` (NEW), `machine-readable/reference.yaml`, `guide/ultimate-guide.md` +- **Sandbox Isolation for Coding Agents** — `guide/security/sandbox-isolation.md` (NEW), `machine-readable/reference.yaml`, `guide/ultimate-guide.md` - Score: 4/5 (High Value — official Docker docs + verified vendor documentation) - Source: [docs.docker.com/ai/sandboxes/](https://docs.docker.com/ai/sandboxes/) (Docker Desktop 4.58+, Jan 2026) - New guide file: Docker Sandboxes (microVM isolation, network policies, custom templates, supported agents) @@ -1623,7 +1623,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - 18 new `sandbox_*` entries in reference.yaml - Evaluation: `docs/resource-evaluations/docker-sandboxes-isolation.md` -- **Claude Code releases tracking: v2.1.27** — `machine-readable/claude-code-releases.yaml`, `guide/claude-code-releases.md` +- **Claude Code releases tracking: v2.1.27** — `machine-readable/claude-code-releases.yaml`, `guide/core/claude-code-releases.md` - `--from-pr` flag to resume sessions linked to GitHub PR number/URL - Sessions auto-linked to PRs when created via `gh pr create` - Context management fixes for Bedrock/Vertex gateway users @@ -1638,7 +1638,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - ROI cross-reference added in cost optimization section - Evaluation: `docs/resource-evaluations/026-contribution-metrics-blog.md` -- **Learning guide: Shen & Tamkin RCT integration** — `guide/learning-with-ai.md` +- **Learning guide: Shen & Tamkin RCT integration** — `guide/roles/learning-with-ai.md` - Source: [arXiv:2601.20245](https://arxiv.org/abs/2601.20245) (Shen & Tamkin, Anthropic Fellows, Jan 2026) - Score: 3/5 (Relevant - Useful complement, high overlap with existing content) - Added RCT data point in §3 "Reality of AI Productivity": 17% skill reduction (n=52, Cohen's d=0.738, p=0.01), no significant speed gain, only ~20% delegation users finished faster @@ -1737,14 +1737,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Added - **Practitioner Insight: Addy Osmani (Google Chrome Team)** — Added to AI Ecosystem Practitioner Insights - - **New entry**: `guide/ai-ecosystem.md` line ~2024 "Addy Osmani (Google Chrome Team)" (~32 lines) + - **New entry**: `guide/ecosystem/ai-ecosystem.md` line ~2024 "Addy Osmani (Google Chrome Team)" (~32 lines) - "The 80% Problem in Agentic Coding" synthesis (January 28, 2026) - Three new failure modes: overengineering, assumption propagation, sycophantic agreement - Comprehension debt concept (distinct from technical debt) - Productivity paradox data: +98% PRs, +91% review time, no workload reduction - Alignment table mapping Osmani concepts to existing guide sections - **Reference updates**: `machine-readable/reference.yaml` — 4 new entries - - `practitioner_addy_osmani: "guide/ai-ecosystem.md:2024"` + - `practitioner_addy_osmani: "guide/ecosystem/ai-ecosystem.md:2024"` - `practitioner_osmani_source: "https://addyo.substack.com/p/the-80-problem-in-agentic-coding"` - `eighty_percent_problem`, `comprehension_debt_secondary` - **Resource evaluation**: `docs/resource-evaluations/024-addy-osmani-80-percent-problem.md` @@ -1793,7 +1793,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Added - **Practitioner Insights** — Peter Steinberger (PSPDFKit Founder, Moltbot Creator) - - Added new practitioner insight in `guide/ai-ecosystem.md` documenting model-agnostic workflow patterns + - Added new practitioner insight in `guide/ecosystem/ai-ecosystem.md` documenting model-agnostic workflow patterns - **Patterns documented**: Stream monitoring, multi-project juggling (3-8 concurrent projects), fresh context validation, iterative exploration - **Source**: [Shipping at Inference-Speed](https://steipete.me/posts/2025/shipping-at-inference-speed) (Dec 2025 blog post) - **Evaluation**: Score 3/5 (Relevant - Useful complement) @@ -1804,7 +1804,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Scope**: Model-agnostic patterns only, zero model comparisons (Codex/Opus excluded as per evaluation decision) - **Note**: Patterns originate from non-Claude workflow (Moltbot/GPT-5.2); validation in Claude Code context recommended - **Files modified**: - - `guide/ai-ecosystem.md`: New entry after Matteo Collina (~26 lines, H3 format with alignment table) + - `guide/ecosystem/ai-ecosystem.md`: New entry after Matteo Collina (~26 lines, H3 format with alignment table) - `docs/resource-evaluations/steinberger-inference-speed.md`: Complete evaluation with challenge agent review - `docs/resource-evaluations/README.md`: Index updated (15→16 evaluations) - `machine-readable/reference.yaml`: Added `practitioner_steinberger` references (line 1997) @@ -1818,14 +1818,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **v2.1.23** (2026-01-29): Customizable spinner verbs, mTLS/proxy fixes, terminal performance improvements - **Files updated**: - `machine-readable/claude-code-releases.yaml`: Updated latest version, added 2 new releases - - `guide/claude-code-releases.md`: Synchronized with YAML, added detailed release notes + - `guide/core/claude-code-releases.md`: Synchronized with YAML, added detailed release notes - **Landing sync**: Updated Claude Code version badge v2.1.22 → v2.1.25 ## [3.18.0] - 2026-01-28 ### Added -- **MCP Servers Ecosystem Documentation** — New `guide/mcp-servers-ecosystem.md` (893 lines) documenting validated community MCP servers +- **MCP Servers Ecosystem Documentation** — New `guide/ecosystem/mcp-servers-ecosystem.md` (893 lines) documenting validated community MCP servers - **8 validated production-ready servers**: - **Playwright MCP** (Microsoft): Browser automation with accessibility trees (Quality: 8.8/10) - **Semgrep MCP** (Semgrep Inc.): Security scanning SAST/secrets/supply chain (Quality: 9.0/10) @@ -1849,7 +1849,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Added -- **Known Issues Tracker** — New `guide/known-issues.md` (285 lines) documenting verified critical bugs +- **Known Issues Tracker** — New `guide/core/known-issues.md` (285 lines) documenting verified critical bugs - **GitHub Issue Auto-Creation Bug**: Verified Issue #13797 (Dec 2025), 17+ confirmed accidental public disclosures - Security/privacy risk: Private project details exposed in public anthropics/claude-code repo - Affected versions: v2.0.65+ @@ -2029,8 +2029,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - Tasks API (v2.1.16+): Official, public, documented in CHANGELOG - CLAUDE_CODE_ENABLE_TASKS: Migration flag (revert to old system), not activation flag - No "hidden features": All public features documented in official CHANGELOG -- **MCP Apps (SEP-1865) Documentation** (`guide/architecture.md`, `guide/ultimate-guide.md`, `machine-readable/reference.yaml`) - - **guide/architecture.md:656**: New section "MCP Extensions: Apps (SEP-1865)" (~150 lines) +- **MCP Apps (SEP-1865) Documentation** (`guide/core/architecture.md`, `guide/ultimate-guide.md`, `machine-readable/reference.yaml`) + - **guide/core/architecture.md:656**: New section "MCP Extensions: Apps (SEP-1865)" (~150 lines) - Technical architecture (2 primitives: tools with UI metadata + UI resources via `ui://` scheme) - Communication flow diagram (MCP Client → Server → Sandboxed Iframe) - Multi-layered security model (sandbox, pre-declared templates, auditable JSON-RPC, user consent, content blocking) @@ -2095,7 +2095,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Added -- **NotebookLM MCP Integration Documentation** (`guide/ai-ecosystem.md`, `guide/ultimate-guide.md`) +- **NotebookLM MCP Integration Documentation** (`guide/ecosystem/ai-ecosystem.md`, `guide/ultimate-guide.md`) - **§ 4.1 NotebookLM MCP Integration** (~240 lines): Complete installation and usage guide - Detailed tool breakdown table: 16 tools across 3 profiles (minimal/standard/full) - Multi-account authentication workflow (authuser parameter for secondary Google accounts) @@ -2153,7 +2153,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Changed -- **guide/methodologies.md:55**: Corrected GSD evaluation link +- **guide/core/methodologies.md:55**: Corrected GSD evaluation link - Old: `../claudedocs/resource-evaluations/gsd-evaluation.md` (private) - New: `../docs/resource-evaluations/gsd-evaluation.md` (public) - **machine-readable/reference.yaml**: Added resource evaluations metadata @@ -2181,14 +2181,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - Boris's practical example: 2.5K tokens grown over months - Anti-pattern warning: no preemptive documentation - Mental model shift: configuration file → organizational learning system - - **Plan-First Discipline** (`guide/methodologies.md:61`) + - **Plan-First Discipline** (`guide/core/methodologies.md:61`) - New "Foundational Discipline" section (between Tier 1 and Tier 2) - Core principle: "Once the plan is good, the code is good" (Boris quote) - Decision table: when to plan first vs when to skip - 3-phase workflow: exploration → validation → execution - Benefits quantified vs "just start coding" - CLAUDE.md integration example for team planning policy - - **Verification Loops architectural pattern** (`guide/methodologies.md:214`) + - **Verification Loops architectural pattern** (`guide/core/methodologies.md:214`) - Extended beyond TDD to general architectural principle - 8 verification domains table (frontend, backend, types, style, performance, accessibility, security, UX) - Boris quote: "An agent that can 'see' what it has done produces better results" @@ -2220,7 +2220,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - Resource evaluation saved in `claudedocs/resource-evaluations/worktrunk-evaluation.md` (score: 3/5 - relevant, useful complement) - Total additions: ~260 lines (121 original + 139 self-assessment) - **machine-readable/reference.yaml**: Added `advanced_worktree_tooling: 10748`, `worktree_tooling_self_assessment: 10762`, and updated line references for all sections after worktrees -- **GSD (Get Shit Done) methodology mention** (`guide/methodologies.md:47-55`) +- **GSD (Get Shit Done) methodology mention** (`guide/core/methodologies.md:47-55`) - Added to Tier 1: Strategic Orchestration alongside BMAD - Meta-prompting 6-phase workflow (Initialize → Discuss → Plan → Execute → Verify → Complete) - Fresh 200k-token contexts per task to avoid context rot @@ -2232,7 +2232,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - Updated final note with adoption metrics and real-world use case examples - Link to comprehensive community analysis: https://docs.google.com/document/d/1Mz4xt1yAqb2gDxjr0Vs_YOu9EeO-6JYQMSx4WWI8KUA/preview - Resource evaluation saved in `claudedocs/resource-evaluations/2026-01-25-clawdbot-twitter-analysis.md` (score: 2/5 - marginal, partial integration) -- **MCP architecture visual diagram** (`guide/architecture.md:513`, SVG) +- **MCP architecture visual diagram** (`guide/core/architecture.md:513`, SVG) - 7-layer security model showing LLM/MCP Server/Tools separation - Visual representation of "No Data Access" (LLM layer) and "Hidden From AI" (Real Systems layer) - Beginner-friendly introduction to MCP architecture with color-coded security boundaries @@ -2272,7 +2272,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Added -- **External orchestration systems documentation** (`guide/ai-ecosystem.md:808`) +- **External orchestration systems documentation** (`guide/ecosystem/ai-ecosystem.md:808`) - Gas Town (Steve Yegge): Multi-agent workspace manager using Claude Code instances - multiclaude (dlorenc): Self-hosted multi-agent Claude Code spawner (383 stars, active development) - agent-chat (Justin Abrahms): Real-time monitoring UI for orchestrator communications (v0.2.0) @@ -2282,7 +2282,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **machine-readable/reference.yaml**: Added `external_orchestrators` section with structured data - Programmatic access to Gas Town, multiclaude, agent-chat metadata - Links to guide sections, GitHub repos, author attribution -- **guide/observability.md:117**: Cross-reference to multi-agent orchestration monitoring +- **guide/ops/observability.md:117**: Cross-reference to multi-agent orchestration monitoring - Architecture pattern for custom implementations (hooks + SQLite + SSE) - Comparison table: external orchestrator monitoring vs native Claude Code monitoring @@ -2300,7 +2300,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - Cross-references to §2.2 (Fresh Context Pattern, line 1525), §2.3 (Plan Mode, line 2100) - Total additions: ~60 lines - **machine-readable/reference.yaml**: Added `vibe_coding_context_overload`, `vibe_coding_context_overload_source`, `vibe_coding_phased_strategy` -- **guide/learning-with-ai.md:96**: Added cross-reference from "Vibe Coding Trap" to new anti-pattern section +- **guide/roles/learning-with-ai.md:96**: Added cross-reference from "Vibe Coding Trap" to new anti-pattern section - **Product Manager FAQ entry** (`guide/ultimate-guide.md:14335`) - Minimal FAQ entry (28 lines) addressing PM workflows with Claude Code @@ -2313,14 +2313,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - Decision: Minimal integration (proportional to source), invite community contribution - Reference YAML: Added `faq_product_managers: 14335` -- **MCP architecture visual diagram** (`guide/architecture.md:513`, SVG) +- **MCP architecture visual diagram** (`guide/core/architecture.md:513`, SVG) - 7-layer security model showing LLM/MCP Server/Tools separation - Visual representation of "No Data Access" (LLM layer) and "Hidden From AI" (Real Systems layer) - Beginner-friendly introduction to MCP architecture with color-coded security boundaries - Design inspired by Dinesh Kumar's LinkedIn visualization, recreated as original work under Apache-2.0 - Includes workflow diagram (5 steps: User Asks → LLM Thinks → MCP Controls → Tools Execute → Safe Result) - Golden rule banner: "LLM Thinks → MCP Controls → Tools Execute → Data Locked" -- **External orchestration systems documentation** (`guide/ai-ecosystem.md:808`) +- **External orchestration systems documentation** (`guide/ecosystem/ai-ecosystem.md:808`) - Gas Town (Steve Yegge): Multi-agent workspace manager using Claude Code instances - multiclaude (dlorenc): Self-hosted multi-agent Claude Code spawner - agent-chat (Justin Abrahms): Real-time monitoring UI for orchestrator communications @@ -2328,7 +2328,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - Security and cost warnings for experimental orchestration systems - **machine-readable/reference.yaml**: Added `external_orchestrators` section with Gas Town, multiclaude, agent-chat - **machine-readable/reference.yaml**: Added `architecture_mcp_visual` (SVG diagram reference) -- **guide/observability.md**: Cross-reference to multi-agent orchestration monitoring +- **guide/ops/observability.md**: Cross-reference to multi-agent orchestration monitoring ## [3.11.7] - 2026-01-25 @@ -2345,7 +2345,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - Related: ClawdBot is self-hosted chatbot for messaging apps (personal automation, smart home); Claude Code is CLI for developers (terminal/IDE, code generation) - Total additions: +76 lines in guide, +3 lines in reference.yaml -- **Architecture Diagrams as Context (Advanced Pattern)** (`guide/ai-ecosystem.md:1379`) +- **Architecture Diagrams as Context (Advanced Pattern)** (`guide/ecosystem/ai-ecosystem.md:1379`) - Pattern documentation for using architecture diagrams in OOP codebases - MCP tools reference: Archy MCP, Mermaid MCP, Blueprint MCP (ArcadeAI) - ACM 2024 research validation for LLM OOP limitations @@ -2354,7 +2354,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - Source: [LinkedIn discussion (Jan 2026)](https://www.linkedin.com/posts/tigraff_uml-claude-wibecoding-activity-7420595633826258944-gGO5) - Evaluation report: `claudedocs/resource-evaluations/uml-oop-diagrams-eval.md` -- **AI Traceability & Attribution Guide** (`guide/ai-traceability.md`) +- **AI Traceability & Attribution Guide** (`guide/ops/ai-traceability.md`) - Comprehensive documentation on AI code attribution and disclosure (~500 lines) - LLVM "Human-in-the-Loop" policy (January 2026): `Assisted-by:` trailer standard - Ghostty mandatory disclosure pattern (August 2025) @@ -2373,15 +2373,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Cross-references added** - `guide/ultimate-guide.md:9256`: Link to AI Traceability Guide after Co-Authored-By section - - `guide/learning-with-ai.md:85`: Related note after Vibe Coding Trap - - `guide/security-hardening.md:476`: PromptPwnd reference in See Also + - `guide/roles/learning-with-ai.md:85`: Related note after Vibe Coding Trap + - `guide/security/security-hardening.md:476`: PromptPwnd reference in See Also - `guide/README.md`: New entry in contents table - **Reference YAML expansion** (`machine-readable/reference.yaml`) - 14 new entries for AI traceability topics - Template locations for disclosure files -- **Architecture Diagrams as Context (Advanced Pattern)** (`guide/ai-ecosystem.md:1379`) +- **Architecture Diagrams as Context (Advanced Pattern)** (`guide/ecosystem/ai-ecosystem.md:1379`) - Pattern documentation for using architecture diagrams in OOP codebases - MCP tools reference: Archy MCP, Mermaid MCP, Blueprint MCP (ArcadeAI) - ACM 2024 research validation for LLM OOP limitations @@ -2448,7 +2448,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - `plugins_marketplace: 6890` (marketplace management reference) - `plugins_recommended: "examples/plugins/"` (new directory) - `plugins_se_cove: "examples/plugins/se-cove.md"` - - `chain_of_verification: "guide/methodologies.md:165"` (methodology reference) + - `chain_of_verification: "guide/core/methodologies.md:165"` (methodology reference) - `chain_of_verification_paper: "https://arxiv.org/abs/2309.11495"` - `chain_of_verification_acl: "https://aclanthology.org/2024.findings-acl.212/"` @@ -2513,7 +2513,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Added -- **skills.sh marketplace documentation** (`guide/ultimate-guide.md:5172`, `guide/ai-ecosystem.md:1284`) +- **skills.sh marketplace documentation** (`guide/ultimate-guide.md:5172`, `guide/ecosystem/ai-ecosystem.md:1284`) - New subsection in Section 5.5: "Skills Marketplace: skills.sh" - Vercel Labs project (launched Jan 21, 2026): centralized skill discovery + one-command install - 200+ skills, leaderboard with 35K+ installs (vercel-react-best-practices top skill) @@ -2523,7 +2523,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - Top skills by category: Frontend (vercel-react, web-design), Database (supabase-postgres), Auth (better-auth), Testing (TDD) - Status documented: Community project (Vercel Labs, not official Anthropic), early stage - Trade-offs: Centralized discovery vs GitHub distribution, multi-agent focus vs Claude Code specific - - Cross-reference added to `guide/ai-ecosystem.md` Section 11.3 (Skills Distribution Platforms) + - Cross-reference added to `guide/ecosystem/ai-ecosystem.md` Section 11.3 (Skills Distribution Platforms) - Complementary resources table updated in README.md - YAML index entries: - `skills_marketplace: 5172` @@ -2537,16 +2537,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Added -- **Matteo Collina practitioner insight** (`guide/ai-ecosystem.md:1243`) +- **Matteo Collina practitioner insight** (`guide/ecosystem/ai-ecosystem.md:1243`) - Node.js TSC Chair's perspective on AI-assisted development - "Bottleneck shift" thesis: judgment becomes the limiting factor, not typing speed - Key quote: "The human in the loop isn't a limitation. It's the point." - Context: Response to Arnaldi's "The Death of Software Development" (January 2026) - Data points: Review time +91% (CodeRabbit), 96% devs don't trust AI code (Sonar 2026) - - Cross-reference added to `guide/learning-with-ai.md` Practitioner Perspectives + - Cross-reference added to `guide/roles/learning-with-ai.md` Practitioner Perspectives - YAML index entries: `practitioner_matteo_collina`, `practitioner_collina_source` -- **Claude Code releases tracking update** (`machine-readable/claude-code-releases.yaml`, `guide/claude-code-releases.md`) +- **Claude Code releases tracking update** (`machine-readable/claude-code-releases.yaml`, `guide/core/claude-code-releases.md`) - Added v2.1.17: Fix for crashes on processors without AVX instruction support - Added v2.1.16: ⭐ New task management system with dependency tracking, VSCode native plugin management, OAuth remote session browsing - Added v2.1.15: npm installations deprecated (migrate to native installer), React Compiler performance improvements @@ -2563,12 +2563,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Added -- **Verification Loops pattern** (`guide/methodologies.md:145`) +- **Verification Loops pattern** (`guide/core/methodologies.md:145`) - Formalized pattern for autonomous iteration with tests as termination condition - Official Anthropic guidance: "Tell Claude to keep going until all tests pass" - Implementation options: Stop hooks, multi-Claude verification, explicit "DONE" markers -- **Eval Harness documentation** (`guide/methodologies.md:161`) +- **Eval Harness documentation** (`guide/core/methodologies.md:161`) - Definition: Infrastructure running evaluations end-to-end - Link to Anthropic source: "Demystifying Evals for AI Agents" @@ -2581,9 +2581,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - Caveats documented: hackathon win was indirect, Node.js hooks not officially recommended - **deep_dive index entries** (`machine-readable/reference.yaml`) - - `verification_loops`: guide/methodologies.md:145 + - `verification_loops`: guide/core/methodologies.md:145 - `verification_loops_source`: Anthropic Best Practices link - - `eval_harness`: guide/methodologies.md:161 + - `eval_harness`: guide/core/methodologies.md:161 - `eval_harness_source`: Demystifying Evals link - **Subscription Token Limits documentation** (`guide/ultimate-guide.md:1933-1995`) @@ -2594,7 +2594,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - Historical note on October 2025 undocumented limit reductions - **Sources**: Perplexity research (Jan 2026), Anthropic support docs, Reddit/GitHub community reports -- **Goose comparison section** (`guide/ai-ecosystem.md:1116-1204`) +- **Goose comparison section** (`guide/ecosystem/ai-ecosystem.md:1116-1204`) - New section "11.1 Goose: Open-Source Alternative (Block)" - Technical comparison table: Claude Code vs Goose on 7 criteria - GitHub stats: 15,400+ stars, 350+ contributors, Apache 2.0 license @@ -2607,10 +2607,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - `subscription_token_budgets: 1948` - `subscription_opus_ratio: 1946` - `subscription_monitoring: 1985` - - `ai_ecosystem_goose: "guide/ai-ecosystem.md:1116"` - - `ai_ecosystem_goose_comparison: "guide/ai-ecosystem.md:1132"` + - `ai_ecosystem_goose: "guide/ecosystem/ai-ecosystem.md:1116"` + - `ai_ecosystem_goose_comparison: "guide/ecosystem/ai-ecosystem.md:1132"` -- **Practitioner Insights section** (`guide/ai-ecosystem.md:1209-1241`) +- **Practitioner Insights section** (`guide/ecosystem/ai-ecosystem.md:1209-1241`) - New section "11.2 Practitioner Insights" for external validation - Dave Van Veen (PhD Stanford, Principal AI Scientist @ HOPPR) - Validates guide patterns: TDD, git worktrees, manual commits, planning phase @@ -2619,11 +2619,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - Updated Table of Contents with new section - **machine-readable/reference.yaml**: Practitioner insights entries - - `practitioner_insights: "guide/ai-ecosystem.md:1209"` - - `practitioner_dave_van_veen: "guide/ai-ecosystem.md:1213"` + - `practitioner_insights: "guide/ecosystem/ai-ecosystem.md:1209"` + - `practitioner_dave_van_veen: "guide/ecosystem/ai-ecosystem.md:1213"` - `ecosystem.practitioner_insights.dave_van_veen` with full metadata -- **OCTO Technology reference** (`guide/learning-with-ai.md:907`) +- **OCTO Technology reference** (`guide/roles/learning-with-ai.md:907`) - Added to "Practitioner Perspectives" section in Sources & Research - Article: "Le développement logiciel à l'ère des agents IA" - Key insights: pairs as minimal team unit (bus factor), bottleneck shifts to functional requirements @@ -2649,17 +2649,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Added -- **Context Packing Tools section** (`guide/ai-ecosystem.md:1114`) +- **Context Packing Tools section** (`guide/ecosystem/ai-ecosystem.md:1114`) - New section "12. Context Packing Tools" documenting gitingest, repo2txt usage patterns - Clarifies when to use external context extraction vs native Claude Code file access - Updated Table of Contents with sections 11 (AI Coding Agents Matrix) and 12 - **machine-readable/reference.yaml**: Added `ai_ecosystem_context_packing` entry -- **Addy Osmani AI Coding Workflow reference** (`guide/methodologies.md:313`) +- **Addy Osmani AI Coding Workflow reference** (`guide/core/methodologies.md:313`) - Added "My AI Coding Workflow in 2026" article to SDD & Spec-First sources - Validates spec-first, TDD, git checkpoints workflow patterns -- **MCP Tool Search documentation** (`guide/architecture.md`) +- **MCP Tool Search documentation** (`guide/core/architecture.md`) - New section "MCP Tool Search (Lazy Loading)" with complete technical details - Explains how Claude Code uses Anthropic's Advanced Tool Use API feature (v2.1.7+) - Includes ASCII diagram of Tool Search flow @@ -2671,7 +2671,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Changed -- **Release notes enrichment** (`guide/claude-code-releases.md`) +- **Release notes enrichment** (`guide/core/claude-code-releases.md`) - v2.1.7: Added 85% token reduction stats, accuracy improvements, Anthropic blog link - v2.1.9: Added `auto:N` configuration examples and cross-reference to architecture.md @@ -2700,7 +2700,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - Mute hierarchy system (project override → project mute → global mute) - Provider auto-detection (macOS Say, Piper TTS) - Audio effects pipeline (reverb, echo, background music) - - **Documentation**: Added section 5.1 "Text-to-Speech Tools" in `guide/ai-ecosystem.md` (80+ lines with tables, quick start, recommendations) + - **Documentation**: Added section 5.1 "Text-to-Speech Tools" in `guide/ecosystem/ai-ecosystem.md` (80+ lines with tables, quick start, recommendations) ### Changed @@ -2801,7 +2801,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ## [3.9.11] - 2026-01-21 ### Added -- **Production Safety Rules Guide** (`guide/production-safety.md`): Comprehensive production safety rules for teams deploying Claude Code in production environments +- **Production Safety Rules Guide** (`guide/security/production-safety.md`): Comprehensive production safety rules for teams deploying Claude Code in production environments - Port Stability: Prevent accidental port changes breaking local dev/Docker/deployed configs - Database Safety: Backup enforcement via PreToolUse hooks to prevent data loss - Feature Completeness: No TODOs for core functionality rules @@ -2868,7 +2868,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Added - **DevOps & SRE Guide** — Comprehensive infrastructure diagnosis guide (~900 lines) - - **New file**: `guide/devops-sre.md` — The FIRE Framework for infrastructure troubleshooting + - **New file**: `guide/ops/devops-sre.md` — The FIRE Framework for infrastructure troubleshooting - **F**irst Response → **I**nvestigate → **R**emediate → **E**valuate - Kubernetes troubleshooting with copy-paste prompts by symptom (CrashLoopBackOff, OOMKilled, ImagePullBackOff, etc.) - Solo incident response workflow (designed for 3 AM scenarios) @@ -2897,7 +2897,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Added - **AI Ecosystem: AI Coding Agents Matrix integration** — Comprehensive ecosystem resource - - **New Section 11** in `guide/ai-ecosystem.md` (~60 lines): "AI Coding Agents Matrix" + - **New Section 11** in `guide/ecosystem/ai-ecosystem.md` (~60 lines): "AI Coding Agents Matrix" - Interactive comparison of 23 AI coding agents across 11 technical criteria - What Is It, Why It's Useful, Complementarity table, Interactive Features, Limitations - Positioning: Discovery (Matrix) → Mastery (This Guide) @@ -3035,7 +3035,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - Developer ↔ Non-Developer workflow patterns - Known issues & troubleshooting - Availability & roadmap - - `guide/ai-ecosystem.md` Section 9 (~90 lines) — Condensed integration guide + - `guide/ecosystem/ai-ecosystem.md` Section 9 (~90 lines) — Condensed integration guide - Quick comparison table - When to use what decision flow - Security considerations summary @@ -3051,7 +3051,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Added -- **Alternative Providers section** in `guide/ai-ecosystem.md` (~55 lines) +- **Alternative Providers section** in `guide/ecosystem/ai-ecosystem.md` (~55 lines) - Documents existence of community workarounds (ANTHROPIC_BASE_URL, etc.) - Clear disclaimer: not tested, not recommended, not supported - Reasons to avoid: feature degradation, ToS risks, no support @@ -3070,7 +3070,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - 11.2 Tool Matrix — Decision guide for when to use which tool - 11.3 Practical Workflows — 4 pipelines (Research→Code, Visual→Code, Documentation, Presentation) - 11.4 Integration Patterns — Full workflows with budget recommendations - - `guide/ai-ecosystem.md` (NEW, ~750 lines) + - `guide/ecosystem/ai-ecosystem.md` (NEW, ~750 lines) - Detailed guide for each complementary tool - Perplexity AI (research with verified sources) - Google Gemini (image understanding → code) @@ -3170,7 +3170,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - When to use each type with decision criteria - Combination patterns for complex workflows -- **Learning with AI guide** for junior developers (`guide/learning-with-ai.md`, ~900 lines) +- **Learning with AI guide** for junior developers (`guide/roles/learning-with-ai.md`, ~900 lines) - **Quick Self-Check** (L31-81): 5 diagnostic questions to assess AI dependency - **Three Developer Patterns** (L82-126): Dependent, Avoidant, Augmented profiles with action paths - **UVAL Protocol** (L127-352): Understand → Verify → Apply → Learn framework @@ -3312,7 +3312,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Added -- **Intellectual Property Considerations** section in `guide/data-privacy.md` +- **Intellectual Property Considerations** section in `guide/security/data-privacy.md` - Disclaimer about legal advice limitations - Key considerations: ownership, license contamination, vendor indemnification, sector compliance - Guidance to consult legal counsel for specific situations @@ -3358,7 +3358,7 @@ cs --json "test" | jq . # JSON for scripting #### Files Modified - `examples/scripts/session-search.sh` - Script v2.1 (367 lines) -- `guide/observability.md` - Documentation updated with new options +- `guide/ops/observability.md` - Documentation updated with new options #### Quality Score Progression @@ -3396,7 +3396,7 @@ Major audit identifying and correcting factual errors that could mislead users a | File | Correction | |------|------------| | guide/ultimate-guide.md | New syntax + warning | -| guide/data-privacy.md | New syntax + deprecation note | +| guide/security/data-privacy.md | New syntax + deprecation note | | examples/scripts/audit-scan.sh | Detection + message fixed | | tools/audit-prompt.md | 3 references corrected | @@ -3408,7 +3408,7 @@ Major audit identifying and correcting factual errors that could mislead users a | File | Correction | |------|------------| | guide/ultimate-guide.md | References → `permissions.deny` | -| guide/data-privacy.md | Section removed | +| guide/security/data-privacy.md | Section removed | | CHANGELOG.md:1244 | Historical reference corrected | #### 4. "Selective Context Loading" Myth → Lazy Loading Reality @@ -3473,7 +3473,7 @@ cs -n 20 # More results |------|-------------| | `examples/scripts/session-search.sh` | Script in repo (source) | | `examples/README.md` | Entry in Scripts table | -| `guide/observability.md` | Section "Session Search & Resume" | +| `guide/ops/observability.md` | Section "Session Search & Resume" | | `guide/ultimate-guide.md:505-524` | Examples in "Finding session IDs" | | `README.md:398-403` | Section "Utility Scripts" | | `machine-readable/reference.yaml` | `deep_dive.session_search` entry | @@ -3493,7 +3493,7 @@ source ~/.zshrc | File | Addition | |------|----------| -| guide/security-hardening.md | Section 1.2 "Known Limitations of permissions.deny" | +| guide/security/security-hardening.md | Section 1.2 "Known Limitations of permissions.deny" | **Content**: - Blocking matrix (Read/Edit/Write/Bash) @@ -3506,9 +3506,9 @@ source ~/.zshrc ``` guide/ultimate-guide.md guide/cheatsheet.md -guide/data-privacy.md -guide/security-hardening.md -guide/observability.md +guide/security/data-privacy.md +guide/security/security-hardening.md +guide/ops/observability.md machine-readable/reference.yaml examples/scripts/audit-scan.sh examples/scripts/session-search.sh (NEW) @@ -3574,7 +3574,7 @@ Documentation alignment and navigation improvements. Comprehensive documentation covering 15 structured development methodologies for AI-assisted development (2025-2026), with practical workflow guides. #### New Files -- **guide/methodologies.md** (NEW, ~400 lines) - Complete methodology reference: +- **guide/core/methodologies.md** (NEW, ~400 lines) - Complete methodology reference: - 15 methodologies organized in 6-tier pyramid (Orchestration → Optimization) - BMAD, SDD, TDD, BDD, DDD, ATDD, CDD, FDD, Context Engineering, Eval-Driven, Multi-Agent, Iterative Loops, Prompt Engineering - Decision tree for choosing the right approach @@ -3621,7 +3621,7 @@ Comprehensive documentation covering 15 structured development methodologies for New comprehensive documentation explaining how Claude Code works internally, based on official Anthropic sources and verified community analysis. #### New Files -- **guide/architecture.md** (NEW, ~800 lines) - Complete technical deep-dive: +- **guide/core/architecture.md** (NEW, ~800 lines) - Complete technical deep-dive: - The Master Loop (`while(tool_call)` architecture) - The Tool Arsenal (8 core tools: Bash, Read, Edit, Write, Grep, Glob, Task, TodoWrite) - Context Management Internals (~200K token budget, auto-compaction) @@ -3718,7 +3718,7 @@ This release combines learnings from the LLM Engineers Handbook (guardrails, obs - Daily/weekly/monthly summaries - Cost estimation with configurable rates - Tool usage and project breakdowns -- **guide/observability.md** - Full observability documentation (~180 lines): +- **guide/ops/observability.md** - Full observability documentation (~180 lines): - Setup instructions, cost tracking, patterns - Limitations clearly documented @@ -3773,7 +3773,7 @@ This release combines learnings from the LLM Engineers Handbook (guardrails, obs ## [3.2.0] - 2026-01-14 ### Added -- **guide/data-privacy.md** - Comprehensive data privacy documentation (NEW, ~200 lines) +- **guide/security/data-privacy.md** - Comprehensive data privacy documentation (NEW, ~200 lines) - TL;DR retention table: 5 years (default) | 30 days (opt-out) | 0 (Enterprise ZDR) - Data flow diagram showing what leaves your machine - Known risks with MCP database connections diff --git a/CLAUDE.md b/CLAUDE.md index 5ad1bd7..ee0c296 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -12,10 +12,13 @@ This repository is the **comprehensive documentation for Claude Code** (Anthropi guide/ # Core documentation ├── ultimate-guide.md # Main guide (~20K lines, the reference) ├── cheatsheet.md # 1-page printable summary -├── architecture.md # How Claude Code works internally -├── methodologies.md # TDD, SDD, BDD workflows -├── data-privacy.md # What data is sent to Anthropic -├── security-hardening.md # Security best practices +├── cowork.md # Cowork redirect page +├── core/ # Architecture, methodologies, releases, known-issues, visual-reference +├── security/ # security-hardening, sandbox-isolation, sandbox-native, production-safety, data-privacy +├── ecosystem/ # ai-ecosystem, mcp-servers-ecosystem, third-party-tools, remarkable-ai +├── roles/ # ai-roles, adoption-approaches, learning-with-ai, agent-evaluation +├── ops/ # devops-sre, observability, ai-traceability +├── diagrams/ # Mermaid visual diagrams └── workflows/ # Step-by-step workflow guides examples/ # Production-ready templates @@ -456,7 +459,7 @@ Ce repo maintient un historique condensé des releases officielles de Claude Cod | Fichier | Rôle | |---------|------| | `machine-readable/claude-code-releases.yaml` | Source de vérité (YAML) | -| `guide/claude-code-releases.md` | Version lisible (Markdown) | +| `guide/core/claude-code-releases.md` | Version lisible (Markdown) | | `scripts/update-cc-releases.sh` | Script de vérification des nouvelles versions | ### Vérifier les nouvelles versions @@ -532,5 +535,5 @@ For answering questions about Claude Code: 1. Search `machine-readable/reference.yaml` first (has line numbers to full guide) 2. Use those line numbers to read relevant sections from `guide/ultimate-guide.md` 3. Check `examples/` for ready-to-use templates -4. Check `guide/claude-code-releases.md` for recent features/changes +4. Check `guide/core/claude-code-releases.md` for recent features/changes 5. Si info manquante ou incertaine → demander une recherche Perplexity (communauté, comparaisons, retours) diff --git a/IDEAS.md b/IDEAS.md index 36c180f..5a5168c 100644 --- a/IDEAS.md +++ b/IDEAS.md @@ -7,7 +7,7 @@ ### MCP Security Hardening ✅ Unified security research covering MCP vulnerabilities, prompt injection, and secret detection. -**Completed**: [Security Hardening Guide](./guide/security-hardening.md) covers: +**Completed**: [Security Hardening Guide](./guide/security/security-hardening.md) covers: - CVE-2025-53109/53110, 54135, 54136 with mitigations - MCP vetting workflow with 5-minute audit checklist - MCP Safe List (community vetted) @@ -119,7 +119,7 @@ Schema-first development impact on Claude Code token consumption. - [ ] 5+ community discussions/issues requesting this topic **If validated (score upgrade to 4/5):** -- Add subsection in `guide/methodologies.md` (after CDD, line 172) +- Add subsection in `guide/core/methodologies.md` (after CDD, line 172) - Use micro-integration template: `docs/resource-evaluations/shiptypes-evaluation.md` (section "Integration Plan") **Check again:** August 2026 diff --git a/README.md b/README.md index a9c9851..716f752 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ Last Update Quiz Templates - Threat Database + Threat Database MCP Server

@@ -36,7 +36,7 @@ | 🎨 **Product Manager / Designer** | [Vibe coding, working with AI-assisted dev teams →](docs/for-product-managers.md) | | ✍️ **Writer / Ops / Manager** | [Claude Cowork Guide (separate repo) →](https://github.com/FlorianBruniaux/claude-cowork-guide) | | 👨‍💻 **Developer (all levels)** | You're in the right place — read on ↓ | -| 🧭 **Career pivot / new AI role** | [AI Roles & Career Paths →](guide/ai-roles.md) | +| 🧭 **Career pivot / new AI role** | [AI Roles & Career Paths →](guide/roles/ai-roles.md) | --- @@ -218,7 +218,7 @@ graph LR **Outcome**: Design your own workflows instead of copy-pasting blindly. **We teach how Claude Code works and why patterns matter**: -- [Architecture](./guide/architecture.md) — Internal mechanics (context flow, tool orchestration, memory management) +- [Architecture](./guide/core/architecture.md) — Internal mechanics (context flow, tool orchestration, memory management) - [Trade-offs](./guide/ultimate-guide.md#when-to-use-what) — Decision frameworks for agents vs skills vs commands - [Configuration Decision Guide](./guide/ultimate-guide.md#27-configuration-decision-guide) — Unified "which mechanism for what?" map across all 7 config layers - [Pitfalls](./guide/ultimate-guide.md#common-mistakes) — Common failure modes + prevention strategies @@ -253,7 +253,7 @@ graph LR - **655 malicious skills catalogued** — Unicode injection, hidden instructions, auto-execute patterns - **Production hardening workflows** — MCP vetting, injection defense, audit automation -[Threat Database →](./machine-readable/threat-db.yaml) | [Security Guide →](./guide/security-hardening.md) +[Threat Database →](./machine-readable/threat-db.yaml) | [Security Guide →](./guide/security/security-hardening.md) **What this means for you**: Vet MCP servers before trusting them, detect attack patterns in configs, comply with security audits. @@ -294,10 +294,10 @@ graph LR **Outcome**: Maintain code quality while working with AI. Complete guides with rationale and examples: -- [TDD](./guide/methodologies.md#1-tdd-test-driven-development-with-claude) — Test-Driven Development (Red-Green-Refactor with AI) -- [SDD](./guide/methodologies.md#2-sdd-specification-driven-development) — Specification-Driven Development (Design before code) -- [BDD](./guide/methodologies.md#3-bdd-behavior-driven-development) — Behavior-Driven Development (User stories → tests) -- [GSD](./guide/methodologies.md#gsd-get-shit-done) — Get Shit Done (Pragmatic delivery) +- [TDD](./guide/core/methodologies.md#1-tdd-test-driven-development-with-claude) — Test-Driven Development (Red-Green-Refactor with AI) +- [SDD](./guide/core/methodologies.md#2-sdd-specification-driven-development) — Specification-Driven Development (Design before code) +- [BDD](./guide/core/methodologies.md#3-bdd-behavior-driven-development) — Behavior-Driven Development (User stories → tests) +- [GSD](./guide/core/methodologies.md#gsd-get-shit-done) — Get Shit Done (Pragmatic delivery) **What this means for you**: Choose the right workflow for your team culture, integrate AI into existing processes, avoid technical debt from AI over-reliance. @@ -342,7 +342,7 @@ Systematic assessment of external resources (5-point scoring): 2. [Essential Commands](./guide/ultimate-guide.md#13-essential-commands) — The 7 commands 3. [Context Management](./guide/ultimate-guide.md#22-context-management) — Critical concept 4. [Memory Files](./guide/ultimate-guide.md#31-memory-files-claudemd) — Your first CLAUDE.md -5. [Learning with AI](./guide/learning-with-ai.md) — Use AI without becoming dependent ⭐ +5. [Learning with AI](./guide/roles/learning-with-ai.md) — Use AI without becoming dependent ⭐ 6. [TDD Workflow](./guide/workflows/tdd-with-claude.md) — Test-first development 7. [Cheat Sheet](./guide/cheatsheet.md) — Print this @@ -353,7 +353,7 @@ Systematic assessment of external resources (5-point scoring): 1. [Core Concepts](./guide/ultimate-guide.md#2-core-concepts) — Mental model 2. [Plan Mode](./guide/ultimate-guide.md#23-plan-mode) — Safe exploration -3. [Methodologies](./guide/methodologies.md) — TDD, SDD, BDD reference +3. [Methodologies](./guide/core/methodologies.md) — TDD, SDD, BDD reference 4. [Agents](./guide/ultimate-guide.md#4-agents) — Custom AI personas 5. [Hooks](./guide/ultimate-guide.md#7-hooks) — Event automation 6. [CI/CD Integration](./guide/ultimate-guide.md#93-cicd-integration) — Pipelines @@ -364,11 +364,11 @@ Systematic assessment of external resources (5-point scoring): Power User — Comprehensive path (8 steps) 1. [Complete Guide](./guide/ultimate-guide.md) — End-to-end -2. [Architecture](./guide/architecture.md) — How Claude Code works -3. [Security Hardening](./guide/security-hardening.md) — MCP vetting, injection defense +2. [Architecture](./guide/core/architecture.md) — How Claude Code works +3. [Security Hardening](./guide/security/security-hardening.md) — MCP vetting, injection defense 4. [MCP Servers](./guide/ultimate-guide.md#8-mcp-servers) — Extended capabilities 5. [Trinity Pattern](./guide/ultimate-guide.md#91-the-trinity) — Advanced workflows -6. [Observability](./guide/observability.md) — Monitor costs & sessions +6. [Observability](./guide/ops/observability.md) — Monitor costs & sessions 7. [Agent Teams](./guide/workflows/agent-teams.md) — Multi-agent coordination (Opus 4.6 experimental) 8. [Examples](./examples/) — Production templates @@ -380,18 +380,18 @@ Systematic assessment of external resources (5-point scoring): **Product Manager** (5 steps): 1. [What's Inside](#-whats-inside) — Scope overview 2. [Golden Rules](#-golden-rules) — Key principles -3. [Data Privacy](./guide/data-privacy.md) — Retention & compliance -4. [Adoption Approaches](./guide/adoption-approaches.md) — Team strategies +3. [Data Privacy](./guide/security/data-privacy.md) — Retention & compliance +4. [Adoption Approaches](./guide/roles/adoption-approaches.md) — Team strategies 5. [PM FAQ](./guide/ultimate-guide.md#can-product-managers-use-claude-code) — Code-adjacent vs non-coding PMs **Note**: Non-coding PMs should consider [Claude Cowork Guide](https://github.com/FlorianBruniaux/claude-cowork-guide) instead. **DevOps / SRE** (5 steps): -1. [DevOps & SRE Guide](./guide/devops-sre.md) — FIRE framework -2. [K8s Troubleshooting](./guide/devops-sre.md#kubernetes-troubleshooting) — Symptom-based prompts -3. [Incident Response](./guide/devops-sre.md#pattern-incident-response) — Workflows -4. [IaC Patterns](./guide/devops-sre.md#pattern-infrastructure-as-code) — Terraform, Ansible -5. [Guardrails](./guide/devops-sre.md#guardrails--adoption) — Security boundaries +1. [DevOps & SRE Guide](./guide/ops/devops-sre.md) — FIRE framework +2. [K8s Troubleshooting](./guide/ops/devops-sre.md#kubernetes-troubleshooting) — Symptom-based prompts +3. [Incident Response](./guide/ops/devops-sre.md#pattern-incident-response) — Workflows +4. [IaC Patterns](./guide/ops/devops-sre.md#pattern-infrastructure-as-code) — Terraform, Ansible +5. [Guardrails](./guide/ops/devops-sre.md#guardrails--adoption) — Security boundaries **Product Designer** (5 steps): 1. [Working with Images](./guide/ultimate-guide.md#24-working-with-images) — Image analysis @@ -610,7 +610,7 @@ claude plugin install session-summary@florian-claude-tools **Community**: 🇫🇷 [Dev With AI](https://www.devw.ai/) — 1500+ devs on Slack, meetups in Paris, Bordeaux, Lyon -→ **[AI Ecosystem Guide](./guide/ai-ecosystem.md)** — Complete integration patterns with complementary AI tools +→ **[AI Ecosystem Guide](./guide/ecosystem/ai-ecosystem.md)** — Complete integration patterns with complementary AI tools --- @@ -646,10 +646,10 @@ claude plugin install session-summary@florian-claude-tools | Resource | Purpose | Time | |----------|---------|------| -| **[Security Hardening Guide](./guide/security-hardening.md)** | MCP vetting, injection defense, audit workflow | 25 min | -| **[Data Privacy Guide](./guide/data-privacy.md)** | Retention policies (5yr → 30d → 0), GDPR compliance | 10 min | -| **[Sandbox Isolation](./guide/sandbox-isolation.md)** | Docker sandboxes for untrusted MCP servers | 10 min | -| **[Production Safety](./guide/production-safety.md)** | Infrastructure locks, port stability, DB safety | 20 min | +| **[Security Hardening Guide](./guide/security/security-hardening.md)** | MCP vetting, injection defense, audit workflow | 25 min | +| **[Data Privacy Guide](./guide/security/data-privacy.md)** | Retention policies (5yr → 30d → 0), GDPR compliance | 10 min | +| **[Sandbox Isolation](./guide/security/sandbox-isolation.md)** | Docker sandboxes for untrusted MCP servers | 10 min | +| **[Production Safety](./guide/security/production-safety.md)** | Infrastructure locks, port stability, DB safety | 20 min | ### Security Commands @@ -683,7 +683,7 @@ claude plugin install session-summary@florian-claude-tools 4. **Testing**: Isolated Docker sandbox first, monitor tool calls 5. **Monitoring**: Session logs, error tracking, regular re-audits -**[Full MCP Security Workflow →](./guide/security-hardening.md#vetting-mcp-servers)** +**[Full MCP Security Workflow →](./guide/security/security-hardening.md#vetting-mcp-servers)** --- @@ -731,20 +731,20 @@ Use this guide critically. Experiment. Share what works for you. |------|---------|------| | **[Ultimate Guide](./guide/ultimate-guide.md)** | Complete reference (20K+ lines), 10 sections | 30-40h (full) • Most consult sections | | **[Cheat Sheet](./guide/cheatsheet.md)** | 1-page printable reference | 5 min | -| **[Visual Reference](./guide/visual-reference.md)** | 20 ASCII diagrams for key concepts | 5 min | -| **[Architecture](./guide/architecture.md)** | How Claude Code works internally | 25 min | -| **[Methodologies](./guide/methodologies.md)** | TDD, SDD, BDD reference | 20 min | +| **[Visual Reference](./guide/core/visual-reference.md)** | 20 ASCII diagrams for key concepts | 5 min | +| **[Architecture](./guide/core/architecture.md)** | How Claude Code works internally | 25 min | +| **[Methodologies](./guide/core/methodologies.md)** | TDD, SDD, BDD reference | 20 min | | **[Workflows](./guide/workflows/)** | Practical guides (TDD, Plan-Driven, Task Management) | 30 min | -| **[Data Privacy](./guide/data-privacy.md)** | Retention & compliance | 10 min | -| **[Security Hardening](./guide/security-hardening.md)** | MCP vetting, injection defense | 25 min | -| **[Sandbox Isolation](./guide/sandbox-isolation.md)** | Docker Sandboxes, cloud alternatives, safe autonomy | 10 min | -| **[Production Safety](./guide/production-safety.md)** | Port stability, DB safety, infrastructure lock | 20 min | -| **[DevOps & SRE](./guide/devops-sre.md)** | FIRE framework, K8s troubleshooting, incident response | 30 min | -| **[AI Ecosystem](./guide/ai-ecosystem.md)** | Complementary AI tools & integration patterns | 20 min | -| **[AI Traceability](./guide/ai-traceability.md)** | Code attribution & provenance tracking | 15 min | -| **[Search Tools Cheatsheet](./guide/search-tools-cheatsheet.md)** | Grep, Serena, ast-grep, grepai comparison | 5 min | -| **[Learning with AI](./guide/learning-with-ai.md)** | Use AI without becoming dependent | 15 min | -| **[Claude Code Releases](./guide/claude-code-releases.md)** | Official release history | 10 min | +| **[Data Privacy](./guide/security/data-privacy.md)** | Retention & compliance | 10 min | +| **[Security Hardening](./guide/security/security-hardening.md)** | MCP vetting, injection defense | 25 min | +| **[Sandbox Isolation](./guide/security/sandbox-isolation.md)** | Docker Sandboxes, cloud alternatives, safe autonomy | 10 min | +| **[Production Safety](./guide/security/production-safety.md)** | Port stability, DB safety, infrastructure lock | 20 min | +| **[DevOps & SRE](./guide/ops/devops-sre.md)** | FIRE framework, K8s troubleshooting, incident response | 30 min | +| **[AI Ecosystem](./guide/ecosystem/ai-ecosystem.md)** | Complementary AI tools & integration patterns | 20 min | +| **[AI Traceability](./guide/ops/ai-traceability.md)** | Code attribution & provenance tracking | 15 min | +| **[Search Tools Cheatsheet](./guide/cheatsheet.md)** | Grep, Serena, ast-grep, grepai comparison | 5 min | +| **[Learning with AI](./guide/roles/learning-with-ai.md)** | Use AI without becoming dependent | 15 min | +| **[Claude Code Releases](./guide/core/claude-code-releases.md)** | Official release history | 10 min |
Examples Library (176 templates) @@ -830,7 +830,7 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines. ### This Guide - **[CHANGELOG](./CHANGELOG.md)** — Guide version history (what's new in each release) -- [Claude Code Releases](./guide/claude-code-releases.md) — Official Claude Code release tracking +- [Claude Code Releases](./guide/core/claude-code-releases.md) — Official Claude Code release tracking ### Official Resources - [Claude Code CLI](https://code.claude.com) — Official website diff --git a/docs/for-cto.md b/docs/for-cto.md index 24113b7..491692b 100644 --- a/docs/for-cto.md +++ b/docs/for-cto.md @@ -102,6 +102,6 @@ If you want to accelerate adoption or get an independent assessment of your curr ## Quick links - Whitepapers — 10 focused deep-dives *(coming soon)* -- [Security Hardening Guide](../guide/security-hardening.md) +- [Security Hardening Guide](../guide/security/security-hardening.md) ← [Back to main README](../README.md) diff --git a/docs/for-tech-leads.md b/docs/for-tech-leads.md index af89c9c..7481e29 100644 --- a/docs/for-tech-leads.md +++ b/docs/for-tech-leads.md @@ -94,7 +94,7 @@ If you want structured onboarding rather than self-learning: - [Full Guide](../guide/ultimate-guide.md) — start at Ch.3.5 for team config - Whitepapers — 10 focused deep-dives *(coming soon)* - [Templates](../examples/) — ready-to-use hooks, agents, CLAUDE.md examples -- [Security Hardening](../guide/security-hardening.md) — threat database + mitigation guide +- [Security Hardening](../guide/security/security-hardening.md) — threat database + mitigation guide - [CHANGELOG](../CHANGELOG.md) — what changed recently ← [Back to main README](../README.md) diff --git a/guide/README.md b/guide/README.md index a5fbef9..e6d6040 100644 --- a/guide/README.md +++ b/guide/README.md @@ -6,54 +6,70 @@ tags: [guide, reference] # Guide Documentation -Core documentation for mastering Claude Code. +Core documentation for mastering Claude Code, organized by topic. -## Contents +--- + +## Core Reference | File | Description | Time | |------|-------------|------| | [ultimate-guide.md](./ultimate-guide.md) | Complete reference covering all Claude Code features | ~3 hours | -| [mcp-servers-ecosystem.md](./mcp-servers-ecosystem.md) | **Community MCP servers**: 8 validated servers (Playwright, Semgrep, Kubernetes, etc.) with production configs | 25 min | -| [third-party-tools.md](./third-party-tools.md) | **Community tools**: GUIs, TUIs, config managers, token trackers, alternative UIs | 15 min | -| [claude-code-releases.md](./claude-code-releases.md) | Official release history (condensed) | 10 min | -| [known-issues.md](./known-issues.md) | **Critical bugs tracker**: security issues, token consumption, verified community reports | 15 min | | [cheatsheet.md](./cheatsheet.md) | 1-page printable quick reference | 5 min | -| [visual-reference.md](./visual-reference.md) | Visual cheatsheet — ASCII diagrams for key concepts | 5 min | +| [core/architecture.md](./core/architecture.md) | How Claude Code works internally (master loop, tools, context) | 25 min | +| [core/methodologies.md](./core/methodologies.md) | 15 development methodologies reference (TDD, SDD, BDD, etc.) | 20 min | +| [core/visual-reference.md](./core/visual-reference.md) | Visual cheatsheet — ASCII diagrams for key concepts | 5 min | +| [core/claude-code-releases.md](./core/claude-code-releases.md) | Official release history (condensed) | 10 min | +| [core/known-issues.md](./core/known-issues.md) | **Critical bugs tracker**: security issues, token consumption, verified community reports | 15 min | | [diagrams/](./diagrams/) | **Visual Diagrams Series**: 41 Mermaid interactive diagrams for model selection, agent lifecycle, security, multi-agent patterns | 15 min | -| [architecture.md](./architecture.md) | How Claude Code works internally (master loop, tools, context) | 25 min | -| [learning-with-ai.md](./learning-with-ai.md) | Guide for juniors on using AI without losing skills | 15 min | -| [adoption-approaches.md](./adoption-approaches.md) | Implementation strategies for teams | 15 min | -| [agent-evaluation.md](./agent-evaluation.md) | **Agent quality metrics**: Measuring custom agent effectiveness with hooks, tests, and feedback loops | 20 min | -| [data-privacy.md](./data-privacy.md) | Data retention and privacy guide | 10 min | -| [observability.md](./observability.md) | Session monitoring and cost tracking | 15 min | -| [methodologies.md](./methodologies.md) | 15 development methodologies reference (TDD, SDD, BDD, etc.) | 20 min | -| [security-hardening.md](./security-hardening.md) | Security threats, MCP vetting, injection defense | 25 min | -| [ai-traceability.md](./ai-traceability.md) | AI attribution, disclosure policies, git-ai, compliance | 20 min | -| [devops-sre.md](./devops-sre.md) | FIRE framework for infrastructure diagnosis and incident response | 30 min | -| [sandbox-isolation.md](./sandbox-isolation.md) | Docker Sandboxes, cloud alternatives, safe autonomy workflows | 10 min | -| [ai-ecosystem.md](./ai-ecosystem.md) | Complementary AI tools (Perplexity, Gemini, Kimi, NotebookLM, TTS) | 30 min | -| [cowork.md](./cowork.md) | Claude Cowork: Summary (see [dedicated repo](https://github.com/FlorianBruniaux/claude-cowork-guide) for full docs) | 5 min | -| [ai-roles.md](./ai-roles.md) | AI roles mapping: when to use Claude Code vs Claude Desktop vs API | 10 min | -| [production-safety.md](./production-safety.md) | Production safety: guardrails, review gates, rollback strategies | 15 min | -| [remarkable-ai.md](./remarkable-ai.md) | Remarkable AI usage patterns and power-user techniques | 10 min | -| [sandbox-native.md](./sandbox-native.md) | Native Claude Code sandbox: configuration and security model | 10 min | -| [search-tools-cheatsheet.md](./search-tools-cheatsheet.md) | Search tools quick reference: rg, grepai, Serena, ast-grep | 5 min | -| [workflows/](./workflows/) | Practical workflow guides for Claude Code | 30 min | -### Cowork Documentation +--- -For knowledge workers using Claude Cowork (agentic desktop): +## Security -| Resource | Description | -|----------|-------------| -| **[Cowork Hub](https://github.com/FlorianBruniaux/claude-cowork-guide/blob/main/README.md)** | Complete Cowork documentation | -| [Getting Started](https://github.com/FlorianBruniaux/claude-cowork-guide/blob/main/guide/01-getting-started.md) | Setup and first workflow | -| [Capabilities](https://github.com/FlorianBruniaux/claude-cowork-guide/blob/main/guide/02-capabilities.md) | What Cowork can/cannot do | -| [Security Guide](https://github.com/FlorianBruniaux/claude-cowork-guide/blob/main/guide/03-security.md) | Safe usage practices | -| [Prompt Library](https://github.com/FlorianBruniaux/claude-cowork-guide/tree/main/prompts) | 50+ ready-to-use prompts | -| [Cheatsheet](https://github.com/FlorianBruniaux/claude-cowork-guide/blob/main/reference/cheatsheet.md) | 1-page quick reference | +| File | Description | Time | +|------|-------------|------| +| [security/security-hardening.md](./security/security-hardening.md) | Security threats, MCP vetting, injection defense | 25 min | +| [security/sandbox-isolation.md](./security/sandbox-isolation.md) | Docker Sandboxes, cloud alternatives, safe autonomy workflows | 10 min | +| [security/sandbox-native.md](./security/sandbox-native.md) | Native Claude Code sandbox: configuration and security model | 10 min | +| [security/production-safety.md](./security/production-safety.md) | Production safety: guardrails, review gates, rollback strategies | 15 min | +| [security/data-privacy.md](./security/data-privacy.md) | Data retention and privacy guide | 10 min | -### Workflows +--- + +## Ecosystem + +| File | Description | Time | +|------|-------------|------| +| [ecosystem/ai-ecosystem.md](./ecosystem/ai-ecosystem.md) | Complementary AI tools (Perplexity, Gemini, Kimi, NotebookLM, TTS) | 30 min | +| [ecosystem/mcp-servers-ecosystem.md](./ecosystem/mcp-servers-ecosystem.md) | **Community MCP servers**: 8 validated servers (Playwright, Semgrep, Kubernetes, etc.) with production configs | 25 min | +| [ecosystem/third-party-tools.md](./ecosystem/third-party-tools.md) | **Community tools**: GUIs, TUIs, config managers, token trackers, alternative UIs | 15 min | +| [ecosystem/remarkable-ai.md](./ecosystem/remarkable-ai.md) | Remarkable AI usage patterns and power-user techniques | 10 min | + +--- + +## Roles & Adoption + +| File | Description | Time | +|------|-------------|------| +| [roles/ai-roles.md](./roles/ai-roles.md) | AI roles mapping: when to use Claude Code vs Claude Desktop vs API | 10 min | +| [roles/adoption-approaches.md](./roles/adoption-approaches.md) | Implementation strategies for teams | 15 min | +| [roles/learning-with-ai.md](./roles/learning-with-ai.md) | Guide for juniors on using AI without losing skills | 15 min | +| [roles/agent-evaluation.md](./roles/agent-evaluation.md) | **Agent quality metrics**: Measuring custom agent effectiveness with hooks, tests, and feedback loops | 20 min | + +--- + +## Operations + +| File | Description | Time | +|------|-------------|------| +| [ops/devops-sre.md](./ops/devops-sre.md) | FIRE framework for infrastructure diagnosis and incident response | 30 min | +| [ops/observability.md](./ops/observability.md) | Session monitoring and cost tracking | 15 min | +| [ops/ai-traceability.md](./ops/ai-traceability.md) | AI attribution, disclosure policies, git-ai, compliance | 20 min | + +--- + +## Workflows Hands-on guides for effective development patterns: @@ -78,11 +94,30 @@ Hands-on guides for effective development patterns: | [workflows/talk-pipeline.md](./workflows/talk-pipeline.md) | 6-stage talk preparation: raw material to slides | | [workflows/team-ai-instructions.md](./workflows/team-ai-instructions.md) | Scale CLAUDE.md across multi-developer teams | +--- + +## Cowork Documentation + +For knowledge workers using Claude Cowork (agentic desktop): + +| Resource | Description | +|----------|-------------| +| **[Cowork Hub](https://github.com/FlorianBruniaux/claude-cowork-guide/blob/main/README.md)** | Complete Cowork documentation | +| [Getting Started](https://github.com/FlorianBruniaux/claude-cowork-guide/blob/main/guide/01-getting-started.md) | Setup and first workflow | +| [Capabilities](https://github.com/FlorianBruniaux/claude-cowork-guide/blob/main/guide/02-capabilities.md) | What Cowork can/cannot do | +| [Security Guide](https://github.com/FlorianBruniaux/claude-cowork-guide/blob/main/guide/03-security.md) | Safe usage practices | +| [Prompt Library](https://github.com/FlorianBruniaux/claude-cowork-guide/tree/main/prompts) | 50+ ready-to-use prompts | +| [Cheatsheet](https://github.com/FlorianBruniaux/claude-cowork-guide/blob/main/reference/cheatsheet.md) | 1-page quick reference | + +--- + ## Recommended Reading Order 1. **New users**: Start with Quick Start section in `ultimate-guide.md` 2. **Daily reference**: Print `cheatsheet.md` -3. **Team leads**: Read `adoption-approaches.md` for rollout strategies +3. **Team leads**: Read `roles/adoption-approaches.md` for rollout strategies +4. **Security focus**: `security/security-hardening.md` then `security/sandbox-isolation.md` +5. **Deep architecture**: `core/architecture.md` then `diagrams/` --- diff --git a/guide/cheatsheet.md b/guide/cheatsheet.md index f28880a..5611fb0 100644 --- a/guide/cheatsheet.md +++ b/guide/cheatsheet.md @@ -221,7 +221,7 @@ Model: Sonnet | Ctx: 89.5k | Cost: $2.11 | Ctx(u): 56.0% | **Sub-agents** | Isolated context, max depth=1 | | **Philosophy** | "Less scaffolding, more model" — trust Claude's reasoning | -**Deep dive**: [Architecture & Internals](./architecture.md) +**Deep dive**: [Architecture & Internals](./core/architecture.md) --- @@ -607,6 +607,24 @@ where.exe claude; claude doctor; claude mcp list --- +## Search Tools Quick Reference + +Quick decision (5 seconds): exact text → `rg` | exact name → `rg`/Serena | concept → grepai | structure → ast-grep + +| Task | Tool | Command | +|------|------|---------| +| "Find TODO comments" | `rg` | `rg "TODO"` | +| "Find auth code" | `grepai` | `grepai search "authentication"` | +| "Who calls login?" | `grepai` | `grepai trace callers "login"` | +| "Get file structure" | `Serena` | `serena get_symbols_overview` | +| "Async without try/catch" | `ast-grep` | `ast-grep "async function $F"` | + +Speed: `rg` (~20ms) → Serena (~100ms) → ast-grep (~200ms) → grepai (~500ms) + +> Full workflows: [workflows/search-tools-mastery.md](./workflows/search-tools-mastery.md) + +--- + ## Resources - **Official docs**: [docs.anthropic.com/claude-code](https://docs.anthropic.com/en/docs/claude-code) diff --git a/guide/architecture.md b/guide/core/architecture.md similarity index 99% rename from guide/architecture.md rename to guide/core/architecture.md index 4cadbd1..4072f92 100644 --- a/guide/architecture.md +++ b/guide/core/architecture.md @@ -369,7 +369,7 @@ Claude system prompts (~5-15K tokens) are **publicly published** by Anthropic as **Core Components**: - **Tool definitions**: Bash, Read, Edit, Write, Grep, Glob, Task, TodoWrite -- **Safety instructions**: Content policies, refusal patterns (see [Security Hardening](./security-hardening.md)) +- **Safety instructions**: Content policies, refusal patterns (see [Security Hardening](../security/security-hardening.md)) - **Behavioral guidelines**: Task-first approach, MVP-first, no over-engineering - **Context instructions**: How to gather and use project context @@ -686,7 +686,7 @@ Claude Code includes built-in **native sandboxing** using OS-level primitives fo - ✅ **Native Sandbox**: Daily development, trusted team, lightweight setup - ✅ **Docker Sandboxes**: Untrusted code, kernel exploit protection, Docker-in-Docker needed -**Deep dive**: See [Native Sandboxing Guide](./sandbox-native.md) for complete technical reference, configuration examples, and troubleshooting. +**Deep dive**: See [Native Sandboxing Guide](../security/sandbox-native.md) for complete technical reference, configuration examples, and troubleshooting. ### Hooks System diff --git a/guide/claude-code-releases.md b/guide/core/claude-code-releases.md similarity index 100% rename from guide/claude-code-releases.md rename to guide/core/claude-code-releases.md diff --git a/guide/known-issues.md b/guide/core/known-issues.md similarity index 100% rename from guide/known-issues.md rename to guide/core/known-issues.md diff --git a/guide/methodologies.md b/guide/core/methodologies.md similarity index 100% rename from guide/methodologies.md rename to guide/core/methodologies.md diff --git a/guide/visual-reference.md b/guide/core/visual-reference.md similarity index 98% rename from guide/visual-reference.md rename to guide/core/visual-reference.md index fe95a48..63c0c0e 100644 --- a/guide/visual-reference.md +++ b/guide/core/visual-reference.md @@ -297,7 +297,7 @@ What data leaves your machine when using Claude Code: └─────────────────────────────────────────────────────────────┘ ``` -→ Source: [data-privacy.md:24](./data-privacy.md) +→ Source: [data-privacy.md:24](../security/data-privacy.md) --- @@ -320,7 +320,7 @@ How a malicious MCP server can exploit the one-time approval model: MITIGATION: Version pinning + hash verification + monitoring ``` -→ Source: [security-hardening.md:33](./security-hardening.md) +→ Source: [security-hardening.md:33](../security/security-hardening.md) --- @@ -355,7 +355,7 @@ Full isolation for autonomous Claude Code sessions: └──────────────────────────────────────────────────────────┘ ``` -→ Source: [sandbox-isolation.md:87](./sandbox-isolation.md) +→ Source: [sandbox-isolation.md:87](../security/sandbox-isolation.md) --- @@ -474,7 +474,7 @@ Starting Claude Code? │ └─ NO → Turnkey, adjust as you go ``` -→ Source: [adoption-approaches.md:51](./adoption-approaches.md) +→ Source: [adoption-approaches.md:51](../roles/adoption-approaches.md) --- @@ -522,7 +522,7 @@ Using Perplexity for research, then Claude Code for implementation: └─────────────────────────────────────────────────────────┘ ``` -→ Source: [ai-ecosystem.md:155](./ai-ecosystem.md) +→ Source: [ai-ecosystem.md:155](../ecosystem/ai-ecosystem.md) --- @@ -677,7 +677,7 @@ Systematic framework for learning with AI without losing your edge: If APPLY fails → go back to VERIFY (you memorized, didn't understand) ``` -> Source: [learning-with-ai.md:208](./learning-with-ai.md) +> Source: [learning-with-ai.md:208](../roles/learning-with-ai.md) --- @@ -721,7 +721,7 @@ The full security document (security-hardening.md) organized as 3 defense layers └─────────────────────────────────────────────────────────────┘ ``` -> Source: [security-hardening.md:24/205/345](./security-hardening.md) +> Source: [security-hardening.md:24/205/345](../security/security-hardening.md) --- @@ -763,7 +763,7 @@ Emergency response when a secret (API key, token, password) is exposed: └─────────────────────────────────────────────────────────┘ ``` -> Source: [security-hardening.md:347](./security-hardening.md) +> Source: [security-hardening.md:347](../security/security-hardening.md) --- diff --git a/guide/diagrams/01-foundations.md b/guide/diagrams/01-foundations.md index 29d1c6b..3fa49c0 100644 --- a/guide/diagrams/01-foundations.md +++ b/guide/diagrams/01-foundations.md @@ -41,16 +41,16 @@ flowchart TD style E1 fill:#B8B8B8,color:#333 click A href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#12-first-workflow" "First Workflow" - click B href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/architecture.md#1-the-master-loop" "Layer 1: System Prompt" + click B href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#1-the-master-loop" "Layer 1: System Prompt" click B1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#31-memory-files-claudemd" "Memory Files (CLAUDE.md)" click C href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#22-context-management" "Layer 2: Context Injection" click C1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#22-context-management" "Context Management" - click D href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/architecture.md#2-the-tool-arsenal" "Layer 3: Tool Definitions" - click D1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/architecture.md#2-the-tool-arsenal" "Tool Arsenal" + click D href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#2-the-tool-arsenal" "Layer 3: Tool Definitions" + click D1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#2-the-tool-arsenal" "Tool Arsenal" click E href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#22-context-management" "Layer 4: Conversation History" click E1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#22-context-management" "Context Management" - click F href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/architecture.md#1-the-master-loop" "Claude API — Master Loop" - click G href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/architecture.md#1-the-master-loop" "Claude Response" + click F href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#1-the-master-loop" "Claude API — Master Loop" + click G href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#1-the-master-loop" "Claude Response" ```
@@ -109,14 +109,14 @@ flowchart LR style J fill:#7BC47F,color:#333 click A href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#12-first-workflow" "First Workflow" - click B href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/architecture.md#1-the-master-loop" "Parse Intent — Master Loop" + click B href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#1-the-master-loop" "Parse Intent — Master Loop" click C href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#22-context-management" "Load Context" click D href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#23-plan-mode" "Plan Actions — Plan Mode" - click E href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/architecture.md#2-the-tool-arsenal" "Execute Tools" - click F href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/architecture.md#1-the-master-loop" "More Tools? — Master Loop" - click G href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/architecture.md#1-the-master-loop" "Collect Results" + click E href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#2-the-tool-arsenal" "Execute Tools" + click F href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#1-the-master-loop" "More Tools? — Master Loop" + click G href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#1-the-master-loop" "Collect Results" click H href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#22-context-management" "Update Context" - click I href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/architecture.md#1-the-master-loop" "Generate Response" + click I href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#1-the-master-loop" "Generate Response" click J href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#12-first-workflow" "Display to User" ``` diff --git a/guide/diagrams/02-context-and-sessions.md b/guide/diagrams/02-context-and-sessions.md index 67fa750..583dcfb 100644 --- a/guide/diagrams/02-context-and-sessions.md +++ b/guide/diagrams/02-context-and-sessions.md @@ -124,13 +124,13 @@ flowchart TD click C href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#31-memory-files-claudemd" "Subdirectory CLAUDE.md" click AM href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#31-memory-files-claudemd" "Auto-Memory Native" click D href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#22-context-management" "In-Conversation Context" - click E href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/architecture.md#3-context-management-internals" "Ephemeral State" + click E href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#3-context-management-internals" "Ephemeral State" click A1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#31-memory-files-claudemd" "Global scope — always persists" click B1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#31-memory-files-claudemd" "Project scope — always persists" click C1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#31-memory-files-claudemd" "Directory scope — always persists" click AM1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#31-memory-files-claudemd" "Cross-session auto-memory" click D1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#22-context-management" "Session scope only" - click E1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/architecture.md#3-context-management-internals" "Session scope only" + click E1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#3-context-management-internals" "Session scope only" ```
diff --git a/guide/diagrams/03-configuration-system.md b/guide/diagrams/03-configuration-system.md index 12fc079..424e707 100644 --- a/guide/diagrams/03-configuration-system.md +++ b/guide/diagrams/03-configuration-system.md @@ -226,7 +226,7 @@ flowchart TD click A href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#71-the-event-system" "User sends message" click UPS href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#71-the-event-system" "UserPromptSubmit Hook" click B href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#71-the-event-system" "PreToolUse Hook" - click C href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/architecture.md#2-the-tool-arsenal" "Tool executes" + click C href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#2-the-tool-arsenal" "Tool executes" click D href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#71-the-event-system" "Tool blocked" click E href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#71-the-event-system" "PostToolUse Hook" click F href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#71-the-event-system" "Next tool or response" diff --git a/guide/diagrams/04-architecture-internals.md b/guide/diagrams/04-architecture-internals.md index 944feaa..321bdca 100644 --- a/guide/diagrams/04-architecture-internals.md +++ b/guide/diagrams/04-architecture-internals.md @@ -38,16 +38,16 @@ flowchart TD style K fill:#B8B8B8,color:#333 click A href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#12-first-workflow" "User Input" - click B href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/architecture.md#1-the-master-loop" "Build System Prompt" - click C href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/architecture.md#1-the-master-loop" "Claude API Call" - click D href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/architecture.md#1-the-master-loop" "Response contains tool calls?" - click E href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/architecture.md#2-the-tool-arsenal" "Parse tool calls" - click F href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/architecture.md#2-the-tool-arsenal" "Execute each tool" - click G href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/architecture.md#1-the-master-loop" "Append tool results" - click H href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/architecture.md#1-the-master-loop" "Extract text response" + click B href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#1-the-master-loop" "Build System Prompt" + click C href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#1-the-master-loop" "Claude API Call" + click D href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#1-the-master-loop" "Response contains tool calls?" + click E href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#2-the-tool-arsenal" "Parse tool calls" + click F href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#2-the-tool-arsenal" "Execute each tool" + click G href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#1-the-master-loop" "Append tool results" + click H href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#1-the-master-loop" "Extract text response" click I href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#12-first-workflow" "Display to User" - click J href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/architecture.md#1-the-master-loop" "User sends next message?" - click K href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/architecture.md#1-the-master-loop" "Session ends" + click J href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#1-the-master-loop" "User sends next message?" + click K href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#1-the-master-loop" "Session ends" ```
@@ -70,7 +70,7 @@ Tool calls? │
-> **Source**: [Architecture: Master Loop](../architecture.md#master-loop) — Line ~72 +> **Source**: [Architecture: Master Loop](../core/architecture.md#master-loop) — Line ~72 --- @@ -129,20 +129,20 @@ flowchart TD style WF1 fill:#B8B8B8,color:#333 style WF2 fill:#B8B8B8,color:#333 - click ROOT href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/architecture.md#2-the-tool-arsenal" "Claude Code Tools" - click R1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/architecture.md#2-the-tool-arsenal" "Glob — Find files by pattern" - click R2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/architecture.md#2-the-tool-arsenal" "Grep — Search file content" - click R3 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/architecture.md#2-the-tool-arsenal" "Read — Read file content" - click R4 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/architecture.md#2-the-tool-arsenal" "LS — List directory" - click W1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/architecture.md#2-the-tool-arsenal" "Write — Create new file" - click W2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/architecture.md#2-the-tool-arsenal" "Edit — Modify existing file" - click W3 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/architecture.md#2-the-tool-arsenal" "MultiEdit — Batch modifications" - click E1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/architecture.md#2-the-tool-arsenal" "Bash — Shell commands" + click ROOT href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#2-the-tool-arsenal" "Claude Code Tools" + click R1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#2-the-tool-arsenal" "Glob — Find files by pattern" + click R2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#2-the-tool-arsenal" "Grep — Search file content" + click R3 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#2-the-tool-arsenal" "Read — Read file content" + click R4 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#2-the-tool-arsenal" "LS — List directory" + click W1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#2-the-tool-arsenal" "Write — Create new file" + click W2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#2-the-tool-arsenal" "Edit — Modify existing file" + click W3 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#2-the-tool-arsenal" "MultiEdit — Batch modifications" + click E1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#2-the-tool-arsenal" "Bash — Shell commands" click E2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#41-what-are-agents" "Task — Spawn sub-agent" - click WB1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/architecture.md#2-the-tool-arsenal" "WebSearch" - click WB2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/architecture.md#2-the-tool-arsenal" "WebFetch" - click WF1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/architecture.md#2-the-tool-arsenal" "TodoWrite — Task list" - click WF2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/architecture.md#2-the-tool-arsenal" "NotebookEdit — Jupyter" + click WB1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#2-the-tool-arsenal" "WebSearch" + click WB2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#2-the-tool-arsenal" "WebFetch" + click WF1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#2-the-tool-arsenal" "TodoWrite — Task list" + click WF2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#2-the-tool-arsenal" "NotebookEdit — Jupyter" ```
@@ -158,7 +158,7 @@ WORKFLOW: TodoWrite, NotebookEdit
-> **Source**: [Architecture: Tools](../architecture.md#tools) — Line ~213 +> **Source**: [Architecture: Tools](../core/architecture.md#tools) — Line ~213 --- @@ -204,7 +204,7 @@ System prompt assembly order:
-> **Source**: [Architecture: System Prompt](../architecture.md#system-prompt) — Line ~354 +> **Source**: [Architecture: System Prompt](../core/architecture.md#system-prompt) — Line ~354 --- @@ -257,4 +257,4 @@ Parent receives: text string
-> **Source**: [Architecture: Sub-Agents](../architecture.md#sub-agents) — Line ~444 +> **Source**: [Architecture: Sub-Agents](../core/architecture.md#sub-agents) — Line ~444 diff --git a/guide/diagrams/05-mcp-ecosystem.md b/guide/diagrams/05-mcp-ecosystem.md index 29b4448..21d1648 100644 --- a/guide/diagrams/05-mcp-ecosystem.md +++ b/guide/diagrams/05-mcp-ecosystem.md @@ -93,7 +93,7 @@ Claude Code
-> **Source**: [MCP Ecosystem](../mcp-servers-ecosystem.md) — Full guide +> **Source**: [MCP Ecosystem](../ecosystem/mcp-servers-ecosystem.md) — Full guide --- @@ -162,7 +162,7 @@ Use result ← JSON-RPC Response ← Return result -> **Source**: [Architecture: MCP](../architecture.md#mcp-architecture) — Line ~795 +> **Source**: [Architecture: MCP](../core/architecture.md#mcp-architecture) — Line ~795 --- @@ -209,7 +209,7 @@ DEFENSE: Read MCP source before installing. Especially check tool descriptions. -> **Source**: [Security: MCP Threats](../security-hardening.md#mcp-threats) — Line ~33 +> **Source**: [Security: MCP Threats](../security/security-hardening.md#mcp-threats) — Line ~33 --- diff --git a/guide/diagrams/08-security-and-production.md b/guide/diagrams/08-security-and-production.md index 0b0774a..e4fb4c9 100644 --- a/guide/diagrams/08-security-and-production.md +++ b/guide/diagrams/08-security-and-production.md @@ -54,18 +54,18 @@ flowchart LR style R3 fill:#E87E2F,color:#fff style BLOCKED fill:#7BC47F,color:#333 - click THREAT href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security-hardening.md" "Threat / Attack" - click P1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security-hardening.md#part-1-prevention-before-you-start" "MCP server vetting" - click P2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security-hardening.md#part-1-prevention-before-you-start" "CLAUDE.md restrictions" - click P3 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security-hardening.md#part-1-prevention-before-you-start" ".claudeignore" - click P4 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security-hardening.md#part-1-prevention-before-you-start" "Minimal permissions" - click D1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security-hardening.md#part-2-detection-while-you-work" "PreToolUse hooks" - click D2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security-hardening.md#part-2-detection-while-you-work" "Audit logs" - click D3 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security-hardening.md#part-2-detection-while-you-work" "Anomaly alerts" - click R1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security-hardening.md#part-3-response-when-things-go-wrong" "Sandbox isolation" - click R2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security-hardening.md#part-3-response-when-things-go-wrong" "Permission gates" - click R3 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security-hardening.md#part-3-response-when-things-go-wrong" "Rollback capability" - click BLOCKED href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security-hardening.md" "Threat contained" + click THREAT href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/security-hardening.md" "Threat / Attack" + click P1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/security-hardening.md#part-1-prevention-before-you-start" "MCP server vetting" + click P2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/security-hardening.md#part-1-prevention-before-you-start" "CLAUDE.md restrictions" + click P3 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/security-hardening.md#part-1-prevention-before-you-start" ".claudeignore" + click P4 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/security-hardening.md#part-1-prevention-before-you-start" "Minimal permissions" + click D1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/security-hardening.md#part-2-detection-while-you-work" "PreToolUse hooks" + click D2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/security-hardening.md#part-2-detection-while-you-work" "Audit logs" + click D3 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/security-hardening.md#part-2-detection-while-you-work" "Anomaly alerts" + click R1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/security-hardening.md#part-3-response-when-things-go-wrong" "Sandbox isolation" + click R2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/security-hardening.md#part-3-response-when-things-go-wrong" "Permission gates" + click R3 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/security-hardening.md#part-3-response-when-things-go-wrong" "Rollback capability" + click BLOCKED href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/security-hardening.md" "Threat contained" ```
@@ -88,7 +88,7 @@ Contained
-> **Source**: [Security Hardening](../security-hardening.md) — Full guide +> **Source**: [Security Hardening](../security/security-hardening.md) — Full guide --- @@ -130,20 +130,20 @@ flowchart TD style J fill:#E87E2F,color:#fff style NOTE fill:#F5E6D3,color:#333 - click A href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/sandbox-native.md" "Using Claude Code" - click B href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/sandbox-native.md" "Running on production server?" - click C href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/sandbox-native.md" "ALWAYS sandbox" - click D href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/sandbox-native.md" "Executing untrusted code?" - click E href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/sandbox-native.md" "What platform?" - click F href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/sandbox-native.md" "macOS Sandbox" - click G href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/sandbox-native.md" "Docker sandbox" - click H href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/sandbox-native.md" "Ephemeral container" - click I href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/sandbox-native.md" "Personal project?" - click J href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/sandbox-native.md" "Comfortable with defaults?" - click K href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/sandbox-native.md" "Default mode" - click L href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/sandbox-native.md" "acceptEdits mode" - click M href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/sandbox-native.md" "Sandbox recommended" - click NOTE href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/sandbox-native.md" "Rule of thumb" + click A href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/sandbox-native.md" "Using Claude Code" + click B href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/sandbox-native.md" "Running on production server?" + click C href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/sandbox-native.md" "ALWAYS sandbox" + click D href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/sandbox-native.md" "Executing untrusted code?" + click E href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/sandbox-native.md" "What platform?" + click F href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/sandbox-native.md" "macOS Sandbox" + click G href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/sandbox-native.md" "Docker sandbox" + click H href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/sandbox-native.md" "Ephemeral container" + click I href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/sandbox-native.md" "Personal project?" + click J href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/sandbox-native.md" "Comfortable with defaults?" + click K href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/sandbox-native.md" "Default mode" + click L href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/sandbox-native.md" "acceptEdits mode" + click M href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/sandbox-native.md" "Sandbox recommended" + click NOTE href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/sandbox-native.md" "Rule of thumb" ```
@@ -163,7 +163,7 @@ Rule: When in doubt, sandbox it.
-> **Source**: [Sandbox Native](../sandbox-native.md) — Line ~512 +> **Source**: [Sandbox Native](../security/sandbox-native.md) — Line ~512 --- @@ -200,18 +200,18 @@ flowchart TD style GG fill:#6DB3F2,color:#fff end - click BA href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/production-safety.md" "Claude writes code (anti-pattern)" - click BB href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/production-safety.md" "Ask Claude to verify" - click BC href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/production-safety.md" "Claude says looks good" - click BD href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/production-safety.md" "Bug in production" - click BE href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/production-safety.md" "Why it fails" - click GA href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/production-safety.md" "Claude writes code (best practice)" - click GB href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/production-safety.md" "Human reviews critical sections" - click GC href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/production-safety.md" "Automated test suite" - click GD href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/production-safety.md" "Different tool validates" - click GE href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/production-safety.md" "All checks pass?" - click GF href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/production-safety.md" "Safe to deploy" - click GG href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/production-safety.md" "Fix before deploy" + click BA href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/production-safety.md" "Claude writes code (anti-pattern)" + click BB href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/production-safety.md" "Ask Claude to verify" + click BC href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/production-safety.md" "Claude says looks good" + click BD href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/production-safety.md" "Bug in production" + click BE href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/production-safety.md" "Why it fails" + click GA href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/production-safety.md" "Claude writes code (best practice)" + click GB href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/production-safety.md" "Human reviews critical sections" + click GC href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/production-safety.md" "Automated test suite" + click GD href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/production-safety.md" "Different tool validates" + click GE href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/production-safety.md" "All checks pass?" + click GF href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/production-safety.md" "Safe to deploy" + click GG href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/production-safety.md" "Fix before deploy" ```
@@ -229,7 +229,7 @@ GOOD: Claude writes → Human reviews (critical sections)
-> **Source**: [Production Safety](../production-safety.md) — Line ~639 +> **Source**: [Production Safety](../security/production-safety.md) — Line ~639 --- diff --git a/guide/diagrams/10-adoption-and-learning.md b/guide/diagrams/10-adoption-and-learning.md index 0d451b9..7957278 100644 --- a/guide/diagrams/10-adoption-and-learning.md +++ b/guide/diagrams/10-adoption-and-learning.md @@ -46,24 +46,24 @@ flowchart TD style D4 fill:#7BC47F,color:#333 style E5 fill:#7BC47F,color:#333 - click A href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/adoption-approaches.md" "Start: New to Claude Code" - click B href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/adoption-approaches.md" "Your background?" + click A href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/roles/adoption-approaches.md" "Start: New to Claude Code" + click B href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/roles/adoption-approaches.md" "Your background?" click C href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#12-first-workflow" "Developer Path" click C1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#12-first-workflow" "Quick Start: first session" click C2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#12-first-workflow" "Workflows: TDD, spec-first, plan-driven" click C3 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#41-what-are-agents" "Advanced: agents, hooks, MCP" - click C4 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/adoption-approaches.md" "Productive developer" - click D href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/adoption-approaches.md" "Non-Tech Path" - click D1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/adoption-approaches.md" "What is Claude Code?" - click D2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/adoption-approaches.md" "Basic usage" - click D3 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/adoption-approaches.md" "Limited scope" - click D4 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/adoption-approaches.md" "Safe basic user" - click E href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/adoption-approaches.md" "Team Lead Path" - click E1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/adoption-approaches.md" "ROI assessment" + click C4 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/roles/adoption-approaches.md" "Productive developer" + click D href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/roles/adoption-approaches.md" "Non-Tech Path" + click D1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/roles/adoption-approaches.md" "What is Claude Code?" + click D2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/roles/adoption-approaches.md" "Basic usage" + click D3 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/roles/adoption-approaches.md" "Limited scope" + click D4 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/roles/adoption-approaches.md" "Safe basic user" + click E href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/roles/adoption-approaches.md" "Team Lead Path" + click E1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/roles/adoption-approaches.md" "ROI assessment" click E2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#31-memory-files-claudemd" "CLAUDE.md strategy" - click E3 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/adoption-approaches.md" "Pilot with 2-3 devs" - click E4 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/adoption-approaches.md" "Gradual rollout" - click E5 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/adoption-approaches.md" "Team adoption" + click E3 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/roles/adoption-approaches.md" "Pilot with 2-3 devs" + click E4 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/roles/adoption-approaches.md" "Gradual rollout" + click E5 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/roles/adoption-approaches.md" "Team adoption" ```
@@ -83,7 +83,7 @@ Your background?
-> **Source**: [Adoption Approaches](../adoption-approaches.md) +> **Source**: [Adoption Approaches](../roles/adoption-approaches.md) --- @@ -114,13 +114,13 @@ flowchart LR style DONE fill:#7BC47F,color:#333 style TRAP fill:#E85D5D,color:#fff - click U href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/learning-with-ai.md" "Use It" - click V href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/learning-with-ai.md" "Verify" - click A href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/learning-with-ai.md" "Adapt" - click L href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/learning-with-ai.md" "Learn" - click NEXT href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/learning-with-ai.md" "More tasks using this pattern?" - click DONE href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/learning-with-ai.md" "Pattern internalized" - click TRAP href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/learning-with-ai.md" "Copy-Paste Trap" + click U href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/roles/learning-with-ai.md" "Use It" + click V href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/roles/learning-with-ai.md" "Verify" + click A href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/roles/learning-with-ai.md" "Adapt" + click L href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/roles/learning-with-ai.md" "Learn" + click NEXT href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/roles/learning-with-ai.md" "More tasks using this pattern?" + click DONE href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/roles/learning-with-ai.md" "Pattern internalized" + click TRAP href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/roles/learning-with-ai.md" "Copy-Paste Trap" ```
@@ -139,7 +139,7 @@ Anti-pattern (AVOID): Accept output → Deploy → Bug → "Claude broke it"
-> **Source**: [Learning with AI](../learning-with-ai.md) — Line ~127 +> **Source**: [Learning with AI](../roles/learning-with-ai.md) — Line ~127 --- diff --git a/guide/diagrams/README.md b/guide/diagrams/README.md index 684b610..16e955d 100644 --- a/guide/diagrams/README.md +++ b/guide/diagrams/README.md @@ -8,7 +8,7 @@ tags: [reference, architecture, diagrams, mermaid] 41 interactive Mermaid diagrams organized in 10 thematic files. Each diagram includes a Mermaid version (rendered natively on GitHub) and an ASCII fallback. -> For ASCII-only diagrams and a printable visual reference → [visual-reference.md](../visual-reference.md) +> For ASCII-only diagrams and a printable visual reference → [visual-reference.md](../core/visual-reference.md) --- @@ -95,4 +95,4 @@ All diagrams use the consistent Bold Guy palette: --- -*Back to [guide/README.md](../README.md) | ASCII diagrams → [visual-reference.md](../visual-reference.md)* +*Back to [guide/README.md](../README.md) | ASCII diagrams → [visual-reference.md](../core/visual-reference.md)* diff --git a/guide/ai-ecosystem.md b/guide/ecosystem/ai-ecosystem.md similarity index 99% rename from guide/ai-ecosystem.md rename to guide/ecosystem/ai-ecosystem.md index b3ac3e1..11a6cc0 100644 --- a/guide/ai-ecosystem.md +++ b/guide/ecosystem/ai-ecosystem.md @@ -1715,7 +1715,7 @@ entire handoff --to="gemini" --task="ui-polish" --require-approval **Status:** Production v1.0+ (macOS/Linux, Windows via WSL) -> **Full docs**: [AI Traceability Guide](./ai-traceability.md#51-entire-cli), [Third-Party Tools](./third-party-tools.md) +> **Full docs**: [AI Traceability Guide](../ops/ai-traceability.md#51-entire-cli), [Third-Party Tools](./third-party-tools.md) #### Security & Cost Warnings diff --git a/guide/mcp-servers-ecosystem.md b/guide/ecosystem/mcp-servers-ecosystem.md similarity index 99% rename from guide/mcp-servers-ecosystem.md rename to guide/ecosystem/mcp-servers-ecosystem.md index e23a3ab..861b0da 100644 --- a/guide/mcp-servers-ecosystem.md +++ b/guide/ecosystem/mcp-servers-ecosystem.md @@ -96,7 +96,7 @@ Claude now supports interactive tools via MCP Apps spec: - **Examples**: Slack drafting, Figma diagrams, Asana timelines - **Announcement**: [Smol.ai Newsletter](https://news.smol.ai/issues/26-01-26-mcp-apps) -- **Deep dive**: See [guide/architecture.md:656](./architecture.md#mcp-extensions-apps-sep-1865) +- **Deep dive**: See [guide/architecture.md:656](../core/architecture.md#mcp-extensions-apps-sep-1865) ### IDE Integration diff --git a/guide/remarkable-ai.md b/guide/ecosystem/remarkable-ai.md similarity index 100% rename from guide/remarkable-ai.md rename to guide/ecosystem/remarkable-ai.md diff --git a/guide/third-party-tools.md b/guide/ecosystem/third-party-tools.md similarity index 98% rename from guide/third-party-tools.md rename to guide/ecosystem/third-party-tools.md index eb5052d..705cbbe 100644 --- a/guide/third-party-tools.md +++ b/guide/ecosystem/third-party-tools.md @@ -30,7 +30,7 @@ This page catalogs **community-built tools that extend Claude Code**. Each tool **What this page is NOT**: - Not a list of AI tools that complement Claude Code (see [AI Ecosystem](./ai-ecosystem.md)) -- Not DIY monitoring scripts (see [Observability](./observability.md)) +- Not DIY monitoring scripts (see [Observability](../ops/observability.md)) - Not MCP server recommendations (see [MCP Servers Ecosystem](./mcp-servers-ecosystem.md)) --- @@ -62,7 +62,7 @@ The most mature cost tracking tool for Claude Code. Parses local session data to **Limitations**: Relies on local JSONL parsing; cost estimates may differ from official Anthropic billing. No team aggregation without manual log merging. > **Cross-ref**: The main guide covers basic ccusage commands at [ultimate-guide.md Section 2.4](./ultimate-guide.md) (cost monitoring). -> For DIY cost tracking with hooks, see [Observability](./observability.md). +> For DIY cost tracking with hooks, see [Observability](../ops/observability.md). --- @@ -189,7 +189,7 @@ A web-based UI for browsing and reading Claude Code conversation history (JSONL **Limitations**: Read-only (cannot edit or resume sessions). No cost data. Requires existing `~/.claude/projects/` history. -> **Cross-ref**: For session search from the CLI, see [session-search.sh](../examples/scripts/session-search.sh) in [Observability](./observability.md). +> **Cross-ref**: For session search from the CLI, see [session-search.sh](../examples/scripts/session-search.sh) in [Observability](../ops/observability.md). --- @@ -274,7 +274,7 @@ ls .git/hooks/ # Verify no conflict with existing hooks Stop criteria: checkpoint > 10 MB/session, push overhead > 5s, or hook conflicts. -> **Cross-ref**: Full Entire workflow with examples at [AI Traceability Guide](./ai-traceability.md#51-entire-cli). For compliance use cases, see [Security Hardening](./security-hardening.md). +> **Cross-ref**: Full Entire workflow with examples at [AI Traceability Guide](../ops/ai-traceability.md#51-entire-cli). For compliance use cases, see [Security Hardening](../security/security-hardening.md). --- @@ -585,8 +585,8 @@ As of February 2026, the community tooling ecosystem has notable gaps: ## Related Resources -- [Observability](./observability.md) - DIY session monitoring, logging hooks, cost tracking scripts +- [Observability](../ops/observability.md) - DIY session monitoring, logging hooks, cost tracking scripts - [AI Ecosystem](./ai-ecosystem.md) - Complementary AI tools (Perplexity, Gemini, NotebookLM) - [MCP Servers Ecosystem](./mcp-servers-ecosystem.md) - Validated community MCP servers -- [Architecture](./architecture.md) - How Claude Code works internally +- [Architecture](../core/architecture.md) - How Claude Code works internally - [Ultimate Guide Section 8](./ultimate-guide.md) - Plugin system and marketplaces diff --git a/guide/ai-traceability.md b/guide/ops/ai-traceability.md similarity index 98% rename from guide/ai-traceability.md rename to guide/ops/ai-traceability.md index f689778..68f9888 100644 --- a/guide/ai-traceability.md +++ b/guide/ops/ai-traceability.md @@ -625,7 +625,7 @@ API_KEY = os.environ['API_KEY'] - Explicit permission prompts for file access - Diff review before commits -See [Security Hardening](./security-hardening.md) for full guidance. +See [Security Hardening](../security/security-hardening.md) for full guidance. ### 6.2 Non-Determinism Risk @@ -795,8 +795,8 @@ See full template: [examples/config/PULL_REQUEST_TEMPLATE-ai.md](../examples/con ### In This Guide - [Git Workflow](./ultimate-guide.md#git-workflow) — Claude Code's default Co-Authored-By behavior -- [Learning with AI](./learning-with-ai.md#the-vibe-coding-trap) — Why understanding AI code matters -- [Security Hardening](./security-hardening.md) — Protecting against prompt injection and other attacks +- [Learning with AI](../roles/learning-with-ai.md#the-vibe-coding-trap) — Why understanding AI code matters +- [Security Hardening](../security/security-hardening.md) — Protecting against prompt injection and other attacks ### External Resources diff --git a/guide/devops-sre.md b/guide/ops/devops-sre.md similarity index 98% rename from guide/devops-sre.md rename to guide/ops/devops-sre.md index d196e55..d1b57fb 100644 --- a/guide/devops-sre.md +++ b/guide/ops/devops-sre.md @@ -314,7 +314,7 @@ Understanding limitations prevents frustration and unsafe reliance. - **Highly confidential incidents**: Data breach investigation (legal implications) - **Simple, obvious fixes**: If you know the answer, just do it - **Compliance-restricted environments**: Check if AI tools are allowed -- **AI-specific security incidents**: Prompt injection detected, MCP compromised, agent exfiltrating data → See [Security Hardening — Response](./security-hardening.md#part-3-response-when-things-go-wrong) for dedicated procedures (kill switch architecture, containment levels, incident timelines) +- **AI-specific security incidents**: Prompt injection detected, MCP compromised, agent exfiltrating data → See [Security Hardening — Response](../security/security-hardening.md#part-3-response-when-things-go-wrong) for dedicated procedures (kill switch architecture, containment levels, incident timelines) ### When Claude Excels @@ -868,8 +868,8 @@ approval_required: - **[Agent Template](../examples/agents/devops-sre.md)**: DevOps/SRE agent persona for Claude - **[CLAUDE.md Template](../examples/claude-md/devops-sre.md)**: Project configuration for DevOps teams -- **[Security Hardening Guide](./security-hardening.md)**: Additional security practices -- **[Architecture Guide](./architecture.md)**: How Claude Code works internally +- **[Security Hardening Guide](../security/security-hardening.md)**: Additional security practices +- **[Architecture Guide](../core/architecture.md)**: How Claude Code works internally --- diff --git a/guide/observability.md b/guide/ops/observability.md similarity index 99% rename from guide/observability.md rename to guide/ops/observability.md index 4af8202..83d1fca 100644 --- a/guide/observability.md +++ b/guide/ops/observability.md @@ -921,6 +921,6 @@ find ~/.claude/logs -name "*.jsonl" -mtime +30 -delete - [Session Search Script](../examples/scripts/session-search.sh) - Fast session search & resume - [Session Logger Hook](../examples/hooks/bash/session-logger.sh) - [Stats Analysis Script](../examples/scripts/session-stats.sh) -- [Third-Party Tools](./third-party-tools.md) - Community GUIs, TUIs, and dashboards (ccusage, ccburn, claude-code-viewer) -- [Data Privacy Guide](./data-privacy.md) - What data leaves your machine +- [Third-Party Tools](../ecosystem/third-party-tools.md) - Community GUIs, TUIs, and dashboards (ccusage, ccburn, claude-code-viewer) +- [Data Privacy Guide](../security/data-privacy.md) - What data leaves your machine - [Cost Optimization](./ultimate-guide.md#cost-optimization) - Tips to reduce spend diff --git a/guide/adoption-approaches.md b/guide/roles/adoption-approaches.md similarity index 100% rename from guide/adoption-approaches.md rename to guide/roles/adoption-approaches.md diff --git a/guide/agent-evaluation.md b/guide/roles/agent-evaluation.md similarity index 98% rename from guide/agent-evaluation.md rename to guide/roles/agent-evaluation.md index 58ec5ca..6990016 100644 --- a/guide/agent-evaluation.md +++ b/guide/roles/agent-evaluation.md @@ -429,8 +429,8 @@ Metrics are useless without action: - **[Agents](./ultimate-guide.md#4-agents)**: Creating custom agents - **[Hooks](./ultimate-guide.md#5-hooks)**: Automation with event hooks -- **[Observability](./observability.md)**: Logging and monitoring strategies -- **[AI Ecosystem](./ai-ecosystem.md#82-domain-specific-agent-frameworks)**: External frameworks like nao +- **[Observability](../ops/observability.md)**: Logging and monitoring strategies +- **[AI Ecosystem](../ecosystem/ai-ecosystem.md#82-domain-specific-agent-frameworks)**: External frameworks like nao --- diff --git a/guide/ai-roles.md b/guide/roles/ai-roles.md similarity index 98% rename from guide/ai-roles.md rename to guide/roles/ai-roles.md index 3a572bc..8d3a858 100644 --- a/guide/ai-roles.md +++ b/guide/roles/ai-roles.md @@ -546,7 +546,7 @@ If you're hiring for any of the roles described in this guide, [reach out](https ## See Also - [Learning to Code with AI](./learning-with-ai.md) — skill development for developers using AI -- [AI Ecosystem: Tools & Integrations](./ai-ecosystem.md) — which tools each role uses -- [Methodologies](./methodologies.md) — TDD, SDD, BDD workflows relevant to AI engineers -- [Architecture](./architecture.md) — how Claude Code works, relevant for AI agent engineers -- [Security Hardening](./security-hardening.md) — critical reading for AI Safety engineers and Platform engineers \ No newline at end of file +- [AI Ecosystem: Tools & Integrations](../ecosystem/ai-ecosystem.md) — which tools each role uses +- [Methodologies](../core/methodologies.md) — TDD, SDD, BDD workflows relevant to AI engineers +- [Architecture](../core/architecture.md) — how Claude Code works, relevant for AI agent engineers +- [Security Hardening](../security/security-hardening.md) — critical reading for AI Safety engineers and Platform engineers \ No newline at end of file diff --git a/guide/learning-with-ai.md b/guide/roles/learning-with-ai.md similarity index 99% rename from guide/learning-with-ai.md rename to guide/roles/learning-with-ai.md index 6776baa..395f7ff 100644 --- a/guide/learning-with-ai.md +++ b/guide/roles/learning-with-ai.md @@ -89,7 +89,7 @@ The struggle isn't optional. It's where learning happens. Term coined by [Andrej Karpathy](https://x.com/karpathy/status/1886192184808149383) (Feb 2025, Collins Word of the Year 2025): coding by "fully giving in to the vibes" without understanding the generated code. -> **Related**: For team and OSS contexts, see [AI Traceability](./ai-traceability.md) for disclosure policies (LLVM, Ghostty, Fedora) and attribution tools. +> **Related**: For team and OSS contexts, see [AI Traceability](../ops/ai-traceability.md) for disclosure policies (LLVM, Ghostty, Fedora) and attribution tools. **Symptoms:** - Accept All without reading diffs @@ -1075,7 +1075,7 @@ Sources for [§3 The Reality of AI Productivity](#the-reality-of-ai-productivity - **ThoughtWorks Technology Radar** — AI-assisted development maturity model - **Martin Fowler on AI Pair Programming** — Patterns for effective human-AI collaboration - **OCTO Technology: Le développement à l'ère des agents IA** — [blog.octo.com](https://blog.octo.com/le-developpement-logiciel-a-l-ere-des-agents-ia) — Organizational perspective on AI-augmented development: pairs as minimal team unit (bus factor), bottleneck shifts from technical to functional requirements, junior developer integration via pair programming and deliberate practice. Managerial focus — useful context for team leads. -- **Matteo Collina: The Human in the Loop** — [adventures.nodeland.dev](https://adventures.nodeland.dev/archive/the-human-in-the-loop/) — Node.js TSC Chair on the bottleneck shift from coding to reviewing. Response to Arnaldi's "Death of Software Development." Key thesis: AI amplifies productivity, but judgment and accountability remain human responsibilities. Quote: "The human in the loop isn't a limitation. It's the point." See [detailed analysis](./ai-ecosystem.md#matteo-collina-nodejs-tsc-chair). +- **Matteo Collina: The Human in the Loop** — [adventures.nodeland.dev](https://adventures.nodeland.dev/archive/the-human-in-the-loop/) — Node.js TSC Chair on the bottleneck shift from coding to reviewing. Response to Arnaldi's "Death of Software Development." Key thesis: AI amplifies productivity, but judgment and accountability remain human responsibilities. Quote: "The human in the loop isn't a limitation. It's the point." See [detailed analysis](../ecosystem/ai-ecosystem.md#matteo-collina-nodejs-tsc-chair). ### Educational Frameworks @@ -1085,7 +1085,7 @@ Sources for [§3 The Reality of AI Productivity](#the-reality-of-ai-productivity ### Methodology References -See [methodologies.md](./methodologies.md) for: +See [methodologies.md](../core/methodologies.md) for: - TDD with AI assistance - Spec-Driven Development - Eval-Driven Development for AI outputs @@ -1105,7 +1105,7 @@ Practitioner reports from real-world usage provide empirical validation of theor ### In This Guide - [AI Roles & Career Paths](./ai-roles.md) — Map of emerging AI roles (Prompt Engineer → Harness Engineer) with career matrix and salary benchmarks -- [Methodologies: TDD with Claude](./methodologies.md#tier-5-implementation) — Write tests first, then implement +- [Methodologies: TDD with Claude](../core/methodologies.md#tier-5-implementation) — Write tests first, then implement - [Workflows: Spec-First](./workflows/spec-first.md) — Understand requirements before code - [Workflows: Plan-Driven](./workflows/plan-driven.md) — Use /plan mode for complex work - [Ultimate Guide: Mental Models](./ultimate-guide.md#mental-model) — How to think about Claude interactions diff --git a/guide/search-tools-cheatsheet.md b/guide/search-tools-cheatsheet.md deleted file mode 100644 index 06ad8b2..0000000 --- a/guide/search-tools-cheatsheet.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: "Search Tools Cheatsheet" -description: "Quick reference for choosing between rg, grepai, Serena and ast-grep" -tags: [cheatsheet, search, reference] ---- - -# Search Tools Cheatsheet (1-Page Reference) - -> **Quick reference for choosing between rg, grepai, Serena & ast-grep** - ---- - -## ⚡ Quick Decision (5 Seconds) - -``` -Know exact text? → rg -Know exact name? → rg or Serena -Know concept? → grepai -Know structure? → ast-grep -Need dependencies? → grepai trace -``` - ---- - -## 📊 Speed vs Intelligence - -``` -Fast ←─────────────────────────────────→ Smart - -rg Serena ast-grep grepai -~20ms ~100ms ~200ms ~500ms - -Exact Symbols Structure Meaning -``` - ---- - -## 🎯 Use Cases (Choose the Right Tool) - -| Task | Tool | Command | -|------|------|---------| -| "Find TODO comments" | `rg` | `rg "TODO"` | -| "Find login function" | `rg`/`Serena` | `rg "login"` or `serena find_symbol` | -| "Find auth code" | `grepai` | `grepai search "authentication"` | -| "Who calls login?" | `grepai` | `grepai trace callers "login"` | -| "Get file structure" | `Serena` | `serena get_symbols_overview` | -| "Async without try/catch" | `ast-grep` | `ast-grep "async function $F"` | -| "React class → hooks" | `ast-grep` | Migration pattern | -| "Remember decision" | `Serena` | `serena write_memory` | - ---- - -## 🔍 Tool Capabilities Matrix - -| Feature | rg | grepai | Serena | ast-grep | -|---------|:--:|:------:|:------:|:--------:| -| **Exact match** | ✅ | ❌ | ✅ | ✅ | -| **Semantic** | ❌ | ✅ | ❌ | ❌ | -| **Call graph** | ❌ | ✅ | ❌ | ❌ | -| **Symbols** | ❌ | ❌ | ✅ | ❌ | -| **AST patterns** | ❌ | ❌ | ❌ | ✅ | -| **Memory** | ❌ | ❌ | ✅ | ❌ | -| **Setup** | ✅ | ⚠️ | ⚠️ | ⚠️ | - ---- - -## 🚀 Combined Workflow (5 Steps) - -**Example: Refactor authentication** - -```bash -# 1. DISCOVER (grepai - semantic) -grepai search "authentication flow" - -# 2. STRUCTURE (Serena - symbols) -serena get_symbols_overview --file auth.service.ts - -# 3. DEPENDENCIES (grepai - call graph) -grepai trace callers "login" - -# 4. PATTERNS (ast-grep - structure) -ast-grep "async function login" - -# 5. VERIFY (rg - exact) -rg "validateSession" --type ts -``` - ---- - -## ⚠️ Common Mistakes - -| ❌ Wrong | ✅ Right | -|---------|---------| -| `grepai search "createSession"` | `rg "createSession"` | -| `rg "auth.*login.*session"` | `grepai search "auth flow"` | -| `rg + sed` for refactoring | `Serena find_symbol` | -| Refactor without checking callers | `grepai trace callers` first | - ---- - -## 📈 When to Escalate - -``` -Start: rg (90% of searches) - ↓ - Need meaning? → grepai - Need symbols? → Serena - Need AST? → ast-grep -``` - ---- - -## 🎓 Full Guide - -📖 [Search Tools Mastery](./workflows/search-tools-mastery.md) - Complete workflows, scenarios, benchmarks - ---- - -**Print this page for quick reference** | Last updated: January 2026 diff --git a/guide/data-privacy.md b/guide/security/data-privacy.md similarity index 100% rename from guide/data-privacy.md rename to guide/security/data-privacy.md diff --git a/guide/production-safety.md b/guide/security/production-safety.md similarity index 99% rename from guide/production-safety.md rename to guide/security/production-safety.md index 707e7b5..ca68ab8 100644 --- a/guide/production-safety.md +++ b/guide/security/production-safety.md @@ -915,7 +915,7 @@ Team settings take precedence, but individuals can opt-in to stricter rules. - [Ultimate Guide §9.12 Git Best Practices](./ultimate-guide.md#912-git-best-practices--workflows) — Commit workflow, Plan → Act pattern - [Security Hardening Guide](./security-hardening.md) — MCP security, secret protection, hook stack - [Data Privacy Guide](./data-privacy.md) — MCP database risks, retention policies -- [Adoption Approaches](./adoption-approaches.md) — Team setup, shared conventions +- [Adoption Approaches](../roles/adoption-approaches.md) — Team setup, shared conventions - [Plan Mode](./ultimate-guide.md#25-plan-mode) — Safe exploration before execution - [Permissions System](./ultimate-guide.md#33-settings--permissions) — Allow/deny rules, hooks diff --git a/guide/sandbox-isolation.md b/guide/security/sandbox-isolation.md similarity index 99% rename from guide/sandbox-isolation.md rename to guide/security/sandbox-isolation.md index be2451c..0b6903d 100644 --- a/guide/sandbox-isolation.md +++ b/guide/security/sandbox-isolation.md @@ -463,7 +463,7 @@ Open-source sandbox platform for AI agents and LLM applications. > **Source**: [code.claude.com/docs/en/sandboxing](https://code.claude.com/docs/en/sandboxing) -Claude Code's built-in process-level sandboxing (Layer 4 in the [architecture](./architecture.md)). +Claude Code's built-in process-level sandboxing (Layer 4 in the [architecture](../core/architecture.md)). - **No external dependencies**: Works out of the box - **Process isolation**: Restricts what commands Claude can execute @@ -558,7 +558,7 @@ For CI/CD, cloud sandboxes (E2B, Vercel, Sprites) are typically better than Dock ## See Also -- [architecture.md](./architecture.md) — Layer 4 (Sub-Agent Architecture) and permission model +- [architecture.md](../core/architecture.md) — Layer 4 (Sub-Agent Architecture) and permission model - [security-hardening.md](./security-hardening.md) — MCP vetting, injection defense, CVE tracking - [code.claude.com/docs/en/sandboxing](https://code.claude.com/docs/en/sandboxing) — Official Claude Code sandbox docs - [docs.docker.com/ai/sandboxes/](https://docs.docker.com/ai/sandboxes/) — Docker Sandboxes documentation diff --git a/guide/sandbox-native.md b/guide/security/sandbox-native.md similarity index 99% rename from guide/sandbox-native.md rename to guide/security/sandbox-native.md index 5759baa..a5955e7 100644 --- a/guide/sandbox-native.md +++ b/guide/security/sandbox-native.md @@ -724,7 +724,7 @@ which bubblewrap socat ## 14. See Also - [Sandbox Isolation (Docker, Cloud)](./sandbox-isolation.md) - microVM-based sandboxing for maximum isolation -- [Architecture: Permission Model](./architecture.md#5-permission--security-model) - How permissions and sandboxing interact +- [Architecture: Permission Model](../core/architecture.md#5-permission--security-model) - How permissions and sandboxing interact - [Official Docs: Sandboxing](https://code.claude.com/docs/en/sandboxing) - Anthropic's official reference - [Official Docs: Security](https://code.claude.com/docs/en/security) - Comprehensive security features - [Official Docs: IAM](https://code.claude.com/docs/en/iam) - Permission configuration diff --git a/guide/security-hardening.md b/guide/security/security-hardening.md similarity index 99% rename from guide/security-hardening.md rename to guide/security/security-hardening.md index e0dc47e..dccc95b 100644 --- a/guide/security-hardening.md +++ b/guide/security/security-hardening.md @@ -671,7 +671,7 @@ fi **Status:** Production v1.0+, SOC2 Type II certified (Entire CLI platform) -> **Full docs**: [AI Traceability Guide](./ai-traceability.md#51-entire-cli), [Third-Party Tools](./third-party-tools.md) +> **Full docs**: [AI Traceability Guide](../ops/ai-traceability.md#51-entire-cli), [Third-Party Tools](../ecosystem/third-party-tools.md) ### 3.5 AI Kill Switch & Containment Architecture @@ -856,7 +856,7 @@ Beyond securing Claude Code itself, Anthropic offers a dedicated vulnerability s ## See Also - [Data Privacy Guide](./data-privacy.md) — Retention policies, compliance, what data leaves your machine -- [AI Traceability](./ai-traceability.md) — PromptPwnd vulnerability, CI/CD security, attribution policies +- [AI Traceability](../ops/ai-traceability.md) — PromptPwnd vulnerability, CI/CD security, attribution policies - [Security Checklist Skill](../examples/skills/security-checklist.md) — OWASP Top 10 patterns for code review - [Security Auditor Agent](../examples/agents/security-auditor.md) — Automated vulnerability detection (read-only) - [Security Patcher Agent](../examples/agents/security-patcher.md) — Applies patches from audit findings (human approval required) diff --git a/guide/ultimate-guide.md b/guide/ultimate-guide.md index 4ac0b90..e4200d6 100644 --- a/guide/ultimate-guide.md +++ b/guide/ultimate-guide.md @@ -796,7 +796,7 @@ You: /exit Session ID: abc123def (saved for resume) ``` -> **Session Search Tools**: For fast session search, see [session-search.sh](../examples/scripts/session-search.sh) (bash, lightweight) and [cc-sessions.py](../examples/scripts/cc-sessions.py) (Python, advanced features: incremental index, partial ID resume, branch filter). Also: [Observability Guide](./observability.md#session-search--resume). +> **Session Search Tools**: For fast session search, see [session-search.sh](../examples/scripts/session-search.sh) (bash, lightweight) and [cc-sessions.py](../examples/scripts/cc-sessions.py) (Python, advanced features: incremental index, partial ID resume, branch filter). Also: [Observability Guide](./ops/observability.md#session-search--resume). **Common use cases**: @@ -834,7 +834,7 @@ Claude: [Continues with full context of Day 1 work] - **Proactive context management**: Monitor with `/status` and use research-backed thresholds: - **< 70%**: Optimal — full reasoning capacity - **75%**: Auto-compact triggers — Claude Code compresses automatically - - **85%**: Manual handoff recommended — start a [session handoff](#session-handoffs) before auto-compact degrades quality ([research-backed](../architecture.md#auto-compaction)) + - **85%**: Manual handoff recommended — start a [session handoff](#session-handoffs) before auto-compact degrades quality ([research-backed](../core/architecture.md#auto-compaction)) - **95%**: Force handoff — severe quality degradation, reset immediately - **Session naming**: Use `/rename` to give sessions descriptive names — critical when running multiple sessions in parallel (see [Auto-Rename Pattern](#session-auto-rename) below) @@ -2184,7 +2184,7 @@ ccusage --model-breakdown # Cost by model (Sonnet/Opus/Haiku) - **Budget planning**: Set monthly spending targets - **Team analytics**: Aggregate costs across developers -> For a full inventory of community cost trackers, session viewers, config managers, and alternative UIs, see [Third-Party Tools](./third-party-tools.md). +> For a full inventory of community cost trackers, session viewers, config managers, and alternative UIs, see [Third-Party Tools](./ecosystem/third-party-tools.md). **Monthly tracking**: @@ -3842,20 +3842,20 @@ When you use Claude Code, the following data leaves your machine: } ``` -> **Warning**: `permissions.deny` has known limitations. See [Security Hardening Guide](./security-hardening.md#known-limitations-of-permissionsdeny) for details. +> **Warning**: `permissions.deny` has known limitations. See [Security Hardening Guide](./security/security-hardening.md#known-limitations-of-permissionsdeny) for details. **2. Never connect production databases** to MCP servers. Use dev/staging with anonymized data. **3. Use security hooks** to block reading of sensitive files (see [Section 7.4](#74-hooks-automating-workflows)). -> **Full guide**: For complete privacy documentation including known risks, community incidents, and enterprise considerations, see [Data Privacy & Retention Guide](./data-privacy.md). +> **Full guide**: For complete privacy documentation including known risks, community incidents, and enterprise considerations, see [Data Privacy & Retention Guide](./security/data-privacy.md). ## 2.11 Under the Hood > **Reading time**: 5 minutes > **Goal**: Understand the core architecture that powers Claude Code -This section provides a summary of Claude Code's internal mechanisms. For the complete technical deep-dive with diagrams and source citations, see the [Architecture & Internals Guide](./architecture.md). +This section provides a summary of Claude Code's internal mechanisms. For the complete technical deep-dive with diagrams and source citations, see the [Architecture & Internals Guide](./core/architecture.md). ### The Master Loop @@ -4162,7 +4162,7 @@ Claude Code operates within a **200K token context window** (1M beta available v | Tool results | Variable | | Reserved for response | 40-45K tokens | -When context fills up (~75% in VS Code, ~95% in CLI), older content is automatically summarized. However, **research shows this degrades quality** (50-70% performance drop on complex tasks). Use `/compact` proactively at logical breakpoints, or trigger **session handoffs at 85%** to preserve intent over compressed history. See [Session Handoffs](line 2140) and [Auto-Compaction Research](../architecture.md#auto-compaction). +When context fills up (~75% in VS Code, ~95% in CLI), older content is automatically summarized. However, **research shows this degrades quality** (50-70% performance drop on complex tasks). Use `/compact` proactively at logical breakpoints, or trigger **session handoffs at 85%** to preserve intent over compressed history. See [Session Handoffs](line 2140) and [Auto-Compaction Research](../core/architecture.md#auto-compaction). ### Sub-Agent Isolation @@ -4364,7 +4364,7 @@ Claude Code trusts the model's reasoning instead of building complex orchestrati | Topic | Where | |-------|-------| -| Full architecture details | [Architecture & Internals Guide](./architecture.md) | +| Full architecture details | [Architecture & Internals Guide](./core/architecture.md) | | Permission system | [Section 7 - Hooks](#7-hooks) | | MCP integration | [Section 8.6 - MCP Security](#86-mcp-security) | | Context management tips | [Section 2.2](#22-context-management) | @@ -7855,7 +7855,7 @@ Design a fintech app with dark theme ### DevOps & SRE Guide -For comprehensive DevOps/SRE workflows, see **[DevOps & SRE Guide](./devops-sre.md)**: +For comprehensive DevOps/SRE workflows, see **[DevOps & SRE Guide](./ops/devops-sre.md)**: - **The FIRE Framework**: First Response → Investigate → Remediate → Evaluate - **Kubernetes troubleshooting**: Prompts by symptom (CrashLoopBackOff, OOMKilled, etc.) - **Incident response**: Solo and multi-agent patterns @@ -7983,7 +7983,7 @@ cp -r /tmp/agent-skills/react-best-practices .claude/skills/ - [Gen + Vercel: Agent Trust Hub partnership](https://www.prnewswire.com/news-releases/gen-and-vercel-partner-to-bring-independent-safety-verification-to-the-ai-skills-ecosystem-302691006.html) - [GitHub: vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills) - [Platform Claude Docs: Skill Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) -- See also: [AI Ecosystem Guide](./ai-ecosystem.md) for complementary tools +- See also: [AI Ecosystem Guide](./ecosystem/ai-ecosystem.md) for complementary tools --- @@ -9232,9 +9232,9 @@ exit 0 Security hooks are critical for protecting your system. -> **Advanced patterns**: For comprehensive security including Unicode injection detection, MCP config integrity verification, and CVE-specific mitigations, see [Security Hardening Guide](./security-hardening.md). +> **Advanced patterns**: For comprehensive security including Unicode injection detection, MCP config integrity verification, and CVE-specific mitigations, see [Security Hardening Guide](./security/security-hardening.md). -> **Claude Code Security (research preview)**: Anthropic offers a dedicated codebase vulnerability scanner that traces data flows across files, challenges findings internally before surfacing them (adversarial validation), and generates patch suggestions. Separate from the Security Auditor Agent above — waitlist access only. See [Security Hardening Guide → Claude Code as Security Scanner](./security-hardening.md#claude-code-as-security-scanner-research-preview). +> **Claude Code Security (research preview)**: Anthropic offers a dedicated codebase vulnerability scanner that traces data flows across files, challenges findings internally before surfacing them (adversarial validation), and generates patch suggestions. Separate from the Security Auditor Agent above — waitlist access only. See [Security Hardening Guide → Claude Code as Security Scanner](./security/security-hardening.md#claude-code-as-security-scanner-research-preview). > > **Validated at scale**: In a March 2026 partnership with Mozilla, Claude Opus 4.6 scanned ~6,000 C++ files in Firefox's JS engine in two weeks, surfacing 22 confirmed vulnerabilities (14 high severity) — roughly one fifth of all high-severity Firefox CVEs fixed in 2025. Demonstrates the model's practical depth for production security work, well beyond surface-level linting. @@ -9498,7 +9498,7 @@ echo '{"tool_name":"Read","tool_input":{"file_path":"$HOME/.env"}}' | \ # Should exit 1 and show "Variable expansion detected" ``` -> **Cross-reference**: For full security hardening including CVE-specific mitigations and MCP config integrity, see [Security Hardening Guide](./security-hardening.md). +> **Cross-reference**: For full security hardening including CVE-specific mitigations and MCP config integrity, see [Security Hardening Guide](./security/security-hardening.md). ## 7.5 Hook Examples @@ -10162,7 +10162,7 @@ MCP Apps is built on the **Model Context Protocol** (open standard by Anthropic) - **SDK**: `@modelcontextprotocol/ext-apps` (npm) - **"Build once, deploy everywhere"**: Works in Claude, VS Code, ChatGPT, Goose -→ **Deep dive**: See [guide/architecture.md:656](./architecture.md#mcp-extensions-apps-sep-1865) for technical architecture, security model, and SDK details. +→ **Deep dive**: See [guide/architecture.md:656](./core/architecture.md#mcp-extensions-apps-sep-1865) for technical architecture, security model, and SDK details. #### Resources @@ -11585,7 +11585,7 @@ A `claude-code-guide` agent is included in `.claude/agents/claude-code-guide.md` Beyond the official servers listed above, the MCP ecosystem includes **validated community servers** that extend Claude Code's capabilities with specialized integrations. -**📖 Complete Guide**: See **[MCP Servers Ecosystem](./mcp-servers-ecosystem.md)** for: +**📖 Complete Guide**: See **[MCP Servers Ecosystem](./ecosystem/mcp-servers-ecosystem.md)** for: - **8 validated production-ready servers**: Playwright (Microsoft), Semgrep, Kubernetes (Red Hat), Context7, Linear, Vercel, Browserbase, MCP-Compose - **Evaluation framework**: How servers are validated (stars, releases, docs, tests, security) @@ -11730,7 +11730,7 @@ claude mcp add --help #### Security Principles -Before implementing secrets management, understand the baseline requirements from [Security Hardening Guide](./security-hardening.md): +Before implementing secrets management, understand the baseline requirements from [Security Hardening Guide](./security/security-hardening.md): - **Encryption at rest**: Secrets must be encrypted on disk (OS keychain > plaintext .env) - **Least privilege**: Use read-only credentials when possible @@ -12648,7 +12648,7 @@ These tools solve different problems at different stages of the development cycl MCP servers extend Claude Code's capabilities, but they also expand its attack surface. Before installing any MCP server, especially community-created ones, apply the same security scrutiny you'd use for any third-party code dependency. -> **CVE details & advanced vetting**: For documented CVEs (2025-53109/53110, 54135, 54136), MCP Safe List, and incident response procedures, see [Security Hardening Guide](./security-hardening.md). +> **CVE details & advanced vetting**: For documented CVEs (2025-53109/53110, 54135, 54136), MCP Safe List, and incident response procedures, see [Security Hardening Guide](./security/security-hardening.md). ### Pre-Installation Checklist @@ -14784,8 +14784,8 @@ exit 0 # Allow - Use `--add-dir` to allow tool access to directories outside the current working directory - Manage thinking mode for cost efficiency: - Simple tasks: Alt+T to disable thinking → faster, cheaper - - Complex tasks: Leave thinking enabled (default in Opus 4.5) - - Note: Keywords like "ultrathink" no longer have effect + - Complex tasks: Leave thinking enabled (default in Opus 4.6) + - `ultrathink` keyword forces high effort for the next turn specifically (re-introduced in v2.1.68) - Set `cleanupPeriodDays` in config to prune old sessions automatically - Use `/compact` proactively when context reaches 70% - Block sensitive files with `permissions.deny` in settings.json @@ -15207,7 +15207,7 @@ For comprehensive AI code attribution beyond Co-Authored-By, including: - git-ai checkpoint tracking - Team and enterprise compliance patterns -See: [AI Traceability Guide](./ai-traceability.md) +See: [AI Traceability Guide](./ops/ai-traceability.md) **Customize commit style in CLAUDE.md:** @@ -16351,7 +16351,7 @@ Time savings from effective Claude Code usage typically far outweigh API costs f ## 9.14 Development Methodologies -> **Full reference**: [methodologies.md](./methodologies.md) | **Hands-on workflows**: [workflows/](./workflows/) +> **Full reference**: [methodologies.md](./core/methodologies.md) | **Hands-on workflows**: [workflows/](./workflows/) 15 structured development methodologies have emerged for AI-assisted development (2025-2026). This section provides quick navigation; detailed workflows are in dedicated files. @@ -16385,7 +16385,7 @@ Time savings from effective Claude Code usage typically far outweigh API costs f | Implementation | TDD, Eval-Driven, Multi-Agent | ⭐⭐⭐ Core workflows | | Optimization | Iterative Loops, Prompt Engineering | ⭐⭐⭐ Foundation | -→ Full descriptions with examples: [methodologies.md](./methodologies.md) +→ Full descriptions with examples: [methodologies.md](./core/methodologies.md) ### SDD Tools (External) @@ -17538,7 +17538,7 @@ Don't jump to 10 instances. Scale progressively with validation gates. | **multiclaude** | Self-hosted spawner | Teams needing on-prem/airgap | | **Entire CLI** | Governance + handoffs | Sequential workflows with compliance | -> **Entire CLI** (Feb 2026): Alternative to parallel orchestration, focuses on **sequential agent handoffs** with governance layer (approval gates, audit trails). Useful for compliance-critical workflows (SOC2, HIPAA) or multi-agent handoffs (Claude → Gemini). See [AI Ecosystem Guide](./ai-ecosystem.md#entire-cli-governance-first-orchestration) for details. +> **Entire CLI** (Feb 2026): Alternative to parallel orchestration, focuses on **sequential agent handoffs** with governance layer (approval gates, audit trails). Useful for compliance-critical workflows (SOC2, HIPAA) or multi-agent handoffs (Claude → Gemini). See [AI Ecosystem Guide](./ecosystem/ai-ecosystem.md#entire-cli-governance-first-orchestration) for details. **Success criteria**: Sustained 3-5% productivity gain over 3 months. @@ -17566,7 +17566,7 @@ Track multi-instance workflows with metrics to validate ROI. ./examples/scripts/session-stats.sh --project backend --range 30d ``` -**See also**: [Session Observability Guide](./observability.md) +**See also**: [Session Observability Guide](./ops/observability.md) #### Warning Signs (Rollback Triggers) @@ -17658,7 +17658,7 @@ New feature request **Related guides**: - [Git worktrees command](../examples/commands/git-worktree.md) - [Database branch setup workflow](../examples/workflows/database-branch-setup.md) -- [Session observability](./observability.md) +- [Session observability](./ops/observability.md) - [Cost optimization](#913-cost-optimization-strategies) **Community discussions**: @@ -20107,7 +20107,7 @@ This section is a quick overview. For complete guide: **Related patterns**: - [§9.17 Multi-Instance Workflows](#917-scaling-patterns-multi-instance-workflows) — Manual parallel coordination - [§4.3 Sub-Agents](#43-sub-agents) — Single-agent task delegation -- [AI Ecosystem: Beads Framework](./ai-ecosystem.md) — Alternative orchestration (Gas Town) +- [AI Ecosystem: Beads Framework](./ecosystem/ai-ecosystem.md) — Alternative orchestration (Gas Town) **Official sources**: - [Introducing Claude Opus 4.6](https://www.anthropic.com/news/claude-opus-4-6) (Anthropic, Feb 2026) @@ -20383,7 +20383,7 @@ This gives you persistent sessions that survive closing your laptop. Combine 6-8 ### Security Considerations -> **Full threat model**: [Security Hardening Guide: Remote Control Security](./security-hardening.md#remote-control-security) +> **Full threat model**: [Security Hardening Guide: Remote Control Security](./security/security-hardening.md#remote-control-security) **Quick summary:** @@ -21932,7 +21932,7 @@ Use when: You need to quickly understand a new codebase or create audio overview **When to use**: Joining new team, reviewing unfamiliar codebase, onboarding prep. -> **💡 MCP Integration Available**: You can now query NotebookLM notebooks directly from Claude Code using the NotebookLM MCP server. See [ai-ecosystem.md § 4.1](./ai-ecosystem.md#41-notebooklm-mcp-integration) for installation and usage guide. +> **💡 MCP Integration Available**: You can now query NotebookLM notebooks directly from Claude Code using the NotebookLM MCP server. See [ai-ecosystem.md § 4.1](./ecosystem/ai-ecosystem.md#41-notebooklm-mcp-integration) for installation and usage guide. ### Presentation Pipeline @@ -22014,7 +22014,7 @@ claude --- -> **📖 Deep Dive**: For detailed integration patterns, ready-to-use prompts, and tool comparisons, see the [complete AI Ecosystem guide](./ai-ecosystem.md). +> **📖 Deep Dive**: For detailed integration patterns, ready-to-use prompts, and tool comparisons, see the [complete AI Ecosystem guide](./ecosystem/ai-ecosystem.md). ### For Non-Developers: Claude Cowork @@ -22031,7 +22031,7 @@ If you work with non-technical team members, **Cowork** brings Claude's agentic **Collaboration pattern**: Developers use Claude Code for specs → PMs use Cowork for stakeholder summaries. Shared context via `~/Shared/CLAUDE.md`. > **Availability**: Pro ($20/mo) or Max ($100-200/mo) subscribers, macOS only (Jan 2026). -> See [AI Ecosystem Section 9](./ai-ecosystem.md#9-claude-cowork-research-preview) for details. +> See [AI Ecosystem Section 9](./ecosystem/ai-ecosystem.md#9-claude-cowork-research-preview) for details. ## Further Reading diff --git a/guide/workflows/agent-teams.md b/guide/workflows/agent-teams.md index 4cdb612..b56ec29 100644 --- a/guide/workflows/agent-teams.md +++ b/guide/workflows/agent-teams.md @@ -1344,11 +1344,11 @@ echo "dist/" >> .gitignore ### Related Documentation -- [Claude Code Releases](../claude-code-releases.md) — v2.1.32, v2.1.33 release notes +- [Claude Code Releases](../core/claude-code-releases.md) — v2.1.32, v2.1.33 release notes - [Sub-Agents](../ultimate-guide.md#sub-agents) — Single-agent task delegation - [Multi-Instance Workflows](../ultimate-guide.md#multi-instance-workflows) — Manual parallel coordination - [Dual-Instance Pattern](../ultimate-guide.md#dual-instance-pattern) — Plan-execute split -- [AI Ecosystem: Beads Framework](../ai-ecosystem.md#beads-framework) — Alternative orchestration (Gas Town) +- [AI Ecosystem: Beads Framework](../ecosystem/ai-ecosystem.md#beads-framework) — Alternative orchestration (Gas Town) --- diff --git a/guide/workflows/iterative-refinement.md b/guide/workflows/iterative-refinement.md index b67aa72..e800c9e 100644 --- a/guide/workflows/iterative-refinement.md +++ b/guide/workflows/iterative-refinement.md @@ -635,4 +635,4 @@ Being honest about what doesn't work yet, so you don't waste time reinventing so - [exploration-workflow.md](./exploration-workflow.md) — Explore alternatives before iterating - [tdd-with-claude.md](./tdd-with-claude.md) — TDD is iterative refinement with tests - [plan-driven.md](./plan-driven.md) — Plan before iterating -- [../methodologies.md](../methodologies.md) — Iterative Loops methodology +- [../core/methodologies.md](../core/methodologies.md) — Iterative Loops methodology diff --git a/guide/workflows/search-tools-mastery.md b/guide/workflows/search-tools-mastery.md index 711de32..e71160e 100644 --- a/guide/workflows/search-tools-mastery.md +++ b/guide/workflows/search-tools-mastery.md @@ -669,7 +669,7 @@ rg "TODO" --type ts - [Serena MCP Guide](../ultimate-guide.md#serena-semantic-code-analysis) - [grepai Documentation](../ultimate-guide.md#grepai-recommended-semantic-search) - [ast-grep Patterns Skill](../../examples/skills/ast-grep-patterns.md) -- [Architecture: Grep vs RAG History](../architecture.md#search-strategy-evolution) +- [Architecture: Grep vs RAG History](../core/architecture.md#search-strategy-evolution) --- diff --git a/guide/workflows/spec-first.md b/guide/workflows/spec-first.md index afcc9ba..e13bd11 100644 --- a/guide/workflows/spec-first.md +++ b/guide/workflows/spec-first.md @@ -861,7 +861,7 @@ Claude: Reads CLAUDE.md + @CLAUDE-api.md (relevant context only) ## See Also -- [../methodologies.md](../methodologies.md) — SDD and other methodologies +- [../core/methodologies.md](../core/methodologies.md) — SDD and other methodologies - [Spec Kit Documentation](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/) - [OpenSpec Documentation](https://github.com/Fission-AI/OpenSpec) - [tdd-with-claude.md](./tdd-with-claude.md) — Combine with TDD diff --git a/guide/workflows/tdd-with-claude.md b/guide/workflows/tdd-with-claude.md index 8ed0b4e..4ce4d92 100644 --- a/guide/workflows/tdd-with-claude.md +++ b/guide/workflows/tdd-with-claude.md @@ -309,7 +309,7 @@ Run tests after each change to ensure they stay green. ## See Also -- [../methodologies.md](../methodologies.md) — Full methodology reference +- [../core/methodologies.md](../core/methodologies.md) — Full methodology reference - [Tight Feedback Loops](../ultimate-guide.md) — Section 9.5 - [examples/skills/tdd-workflow.md](../../examples/skills/tdd-workflow.md) — TDD skill template - [Anthropic Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices) diff --git a/machine-readable/reference.yaml b/machine-readable/reference.yaml index ab7608f..3c003bb 100644 --- a/machine-readable/reference.yaml +++ b/machine-readable/reference.yaml @@ -9,7 +9,7 @@ updated: "2026-03-03" # ════════════════════════════════════════════════════════════════ # DEEP DIVE - Line numbers in guide/ultimate-guide.md # Usage: Read file at line N for detailed documentation on topic -# For architecture internals, see guide/architecture.md +# For architecture internals, see guide/core/architecture.md # ════════════════════════════════════════════════════════════════ deep_dive: # Visual Diagrams Series (40 Mermaid diagrams) @@ -22,11 +22,11 @@ deep_dive: exploration_workflow: "guide/workflows/exploration-workflow.md" script_generation: "guide/workflows/iterative-refinement.md:200" anti_anchoring_prompts: "examples/semantic-anchors/anchor-catalog.md:248" - session_limits: "guide/architecture.md:442" + session_limits: "guide/core/architecture.md:442" claudemd_sizing: 3054 - scope_success_rates: "guide/adoption-approaches.md:26" + scope_success_rates: "guide/roles/adoption-approaches.md:26" # Claude Code Releases - claude_code_releases: "guide/claude-code-releases.md" + claude_code_releases: "guide/core/claude-code-releases.md" claude_code_releases_yaml: "machine-readable/claude-code-releases.yaml" # Code Review Automation (Pat Cullen, Jan 2026) review_pr_advanced: "examples/commands/review-pr.md:81" @@ -69,29 +69,29 @@ deep_dive: team_ai_instructions_token_savings: "59% context token reduction (measured, 5-dev team)" team_ai_instructions_threshold: "Team 5+ devs with multiple AI tools" # Known Issues & Critical Bugs (verified community reports) - known_issues: "guide/known-issues.md" - known_issues_github_bug: "guide/known-issues.md:7" # GitHub auto-creation bug - known_issues_token_consumption: "guide/known-issues.md:105" # Excessive token usage - known_issues_model_quality_aug2025: "guide/known-issues.md:197" # Resolved: Aug 2025 degradation + known_issues: "guide/core/known-issues.md" + known_issues_github_bug: "guide/core/known-issues.md:7" # GitHub auto-creation bug + known_issues_token_consumption: "guide/core/known-issues.md:105" # Excessive token usage + known_issues_model_quality_aug2025: "guide/core/known-issues.md:197" # Resolved: Aug 2025 degradation # Template Installation install_templates_script: "scripts/install-templates.sh" # Session management - session_search: "guide/observability.md:38" + session_search: "guide/ops/observability.md:38" session_search_script: "examples/scripts/session-search.sh" cc_sessions_script: "examples/scripts/cc-sessions.py" - session_resume_limitations: "guide/observability.md:126" - session_cross_folder_migration: "guide/observability.md:126" - session_migration_manual: "guide/observability.md:126" - session_migration_risks: "guide/observability.md:126" - session_migration_community_tool: "guide/observability.md:52" + session_resume_limitations: "guide/ops/observability.md:126" + session_cross_folder_migration: "guide/ops/observability.md:126" + session_migration_manual: "guide/ops/observability.md:126" + session_migration_risks: "guide/ops/observability.md:126" + session_migration_community_tool: "guide/ops/observability.md:52" session_migration_issue: "https://github.com/anthropics/claude-code/issues/1516" session_migration_weller_skill: "https://github.com/jimweller/dotfiles/tree/main/dotfiles/claude-code/skills/claude-migrate-session" # Activity monitoring - activity_monitoring: "guide/observability.md:467" # Tool call audit via JSONL - activity_monitoring_queries: "guide/observability.md:467" # jq queries for audit - activity_monitoring_alerts: "guide/observability.md:467" # Sensitive pattern detection - external_monitoring_tools: "guide/observability.md:527" # ccusage, claude-code-otel, Akto, MLflow, ccboard - proxying_claude_code: "guide/observability.md:699" # Proxyman, mitmproxy, ANTHROPIC_API_URL + activity_monitoring: "guide/ops/observability.md:467" # Tool call audit via JSONL + activity_monitoring_queries: "guide/ops/observability.md:467" # jq queries for audit + activity_monitoring_alerts: "guide/ops/observability.md:467" # Sensitive pattern detection + external_monitoring_tools: "guide/ops/observability.md:527" # ccusage, claude-code-otel, Akto, MLflow, ccboard + proxying_claude_code: "guide/ops/observability.md:699" # Proxyman, mitmproxy, ANTHROPIC_API_URL ccboard_activity_plan: "docs/resource-evaluations/ccboard-activity-module-plan.md" # Cost optimization - Local execution bridge bridge_script: "examples/scripts/bridge.py" @@ -102,7 +102,7 @@ deep_dive: rtk_website: "https://www.rtk-ai.app/" rtk_evaluation: "docs/resource-evaluations/rtk-evaluation.md" rtk_guide: "guide/ultimate-guide.md:14553" - rtk_third_party: "guide/third-party-tools.md:7" + rtk_third_party: "guide/ecosystem/third-party-tools.md:7" rtk_claude_md: "examples/claude-md/rtk-optimized.md" rtk_skill: "examples/skills/rtk-optimizer/SKILL.md" rtk_hook: "examples/hooks/bash/rtk-auto-wrapper.sh" @@ -111,7 +111,7 @@ deep_dive: rtk_score: "5/5" rtk_installation: "cargo install rtk or brew install rtk-ai/tap/rtk" # Google Antigravity (Agent-First IDE) - antigravity_guide: "guide/ai-ecosystem.md:1366" + antigravity_guide: "guide/ecosystem/ai-ecosystem.md:1366" antigravity_evaluation: "docs/resource-evaluations/google-antigravity-evaluation.md" antigravity_proxy: "https://www.npmjs.com/package/antigravity-claude-proxy" antigravity_codelabs: "https://codelabs.developers.google.com/getting-started-google-antigravity" @@ -136,35 +136,35 @@ deep_dive: talk_pipeline_patterns: "skill chaining + file-based state + tool permission scoping + human-in-the-loop gate + AI-to-AI handoff (Claude → Kimi)" talk_pipeline_checkpoint: "Stage 4 CHECKPOINT: user selects angle + title before script starts" talk_pipeline_kimi: "kimi.com (free) — copy-paste Stage 5 prompt for AI slide generation" - # reMarkable 2 + AI (guide/remarkable-ai.md) - remarkable_ai_guide: "guide/remarkable-ai.md" - remarkable_mcp_server: "guide/remarkable-ai.md#1-remarkable-mcp--le-game-changer" + # reMarkable 2 + AI (guide/ecosystem/remarkable-ai.md) + remarkable_ai_guide: "guide/ecosystem/remarkable-ai.md" + remarkable_mcp_server: "guide/ecosystem/remarkable-ai.md#1-remarkable-mcp--le-game-changer" remarkable_mcp_repo: "https://github.com/SamMorrowDrums/remarkable-mcp" - remarkable_ghostwriter: "guide/remarkable-ai.md#2-ghostwriter--interface-vision-llm" - remarkable_obsidian_sync: "guide/remarkable-ai.md#3-sync-remarkable--obsidian" - remarkable_ocr_pipeline: "guide/remarkable-ai.md#4-ocr--ai-pipeline-custom" - remarkable_ssh_tools: "guide/remarkable-ai.md#5-accès-ssh-et-outils-communautaires" - remarkable_meeting_workflow: "guide/remarkable-ai.md#10-meeting-notes--ai-summary" - remarkable_workflows_to_build: "guide/remarkable-ai.md#14-workflows-ai-augmentés-à-construire" - remarkable_getting_started: "guide/remarkable-ai.md#15-par-où-commencer" + remarkable_ghostwriter: "guide/ecosystem/remarkable-ai.md#2-ghostwriter--interface-vision-llm" + remarkable_obsidian_sync: "guide/ecosystem/remarkable-ai.md#3-sync-remarkable--obsidian" + remarkable_ocr_pipeline: "guide/ecosystem/remarkable-ai.md#4-ocr--ai-pipeline-custom" + remarkable_ssh_tools: "guide/ecosystem/remarkable-ai.md#5-accès-ssh-et-outils-communautaires" + remarkable_meeting_workflow: "guide/ecosystem/remarkable-ai.md#10-meeting-notes--ai-summary" + remarkable_workflows_to_build: "guide/ecosystem/remarkable-ai.md#14-workflows-ai-augmentés-à-construire" + remarkable_getting_started: "guide/ecosystem/remarkable-ai.md#15-par-où-commencer" remarkable_community: "https://github.com/reHackable/awesome-reMarkable" # Whitepapers (FR + EN) — 9 focused whitepapers on Claude Code whitepapers_url: "https://www.florian.bruniaux.com/guides" whitepapers_fr: "whitepapers/fr/" # FR sources (Quarto .qmd) whitepapers_en: "whitepapers/en/" # EN sources (Quarto .qmd) whitepapers_topics: "foundations, prompting, customization, security, architecture, team, privacy, reference, agent-teams" - # Learning with AI (guide/learning-with-ai.md) - learning_quick_check: "guide/learning-with-ai.md:38" - learning_uval_protocol: "guide/learning-with-ai.md:218" - learning_claude_config: "guide/learning-with-ai.md:458" - learning_breaking_dependency: "guide/learning-with-ai.md:575" - learning_embracing_ai: "guide/learning-with-ai.md:623" - learning_30day_plan: "guide/learning-with-ai.md:815" - learning_red_flags: "guide/learning-with-ai.md:612" + # Learning with AI (guide/roles/learning-with-ai.md) + learning_quick_check: "guide/roles/learning-with-ai.md:38" + learning_uval_protocol: "guide/roles/learning-with-ai.md:218" + learning_claude_config: "guide/roles/learning-with-ai.md:458" + learning_breaking_dependency: "guide/roles/learning-with-ai.md:575" + learning_embracing_ai: "guide/roles/learning-with-ai.md:623" + learning_30day_plan: "guide/roles/learning-with-ai.md:815" + learning_red_flags: "guide/roles/learning-with-ai.md:612" # Productivity Research RCTs - productivity_rct_metr: "guide/learning-with-ai.md:925" # METR 2025: experienced devs 19% slower on large codebases despite perceiving 20% faster - productivity_rct_echoes: "guide/learning-with-ai.md:926" # Borg 2025: 30.7% faster (median), ~55.9% habitual users, no maintainability impact downstream - productivity_maintainability_empirical: "guide/learning-with-ai.md:926" # Empirical data on "AI code is unmaintainable" claim — blind RCT shows no significant difference + productivity_rct_metr: "guide/roles/learning-with-ai.md:925" # METR 2025: experienced devs 19% slower on large codebases despite perceiving 20% faster + productivity_rct_echoes: "guide/roles/learning-with-ai.md:926" # Borg 2025: 30.7% faster (median), ~55.9% habitual users, no maintainability impact downstream + productivity_maintainability_empirical: "guide/roles/learning-with-ai.md:926" # Empirical data on "AI code is unmaintainable" claim — blind RCT shows no significant difference trust_calibration_maintainability_nuance: "guide/ultimate-guide.md:1097" # Nuance: defect rates ≠ maintenance burden (Borg et al. 2025) session_naming_template: "examples/claude-md/session-naming.md" session_naming_guide: "guide/ultimate-guide.md:815" @@ -175,23 +175,23 @@ deep_dive: learn_alternatives_command: "examples/commands/learn/alternatives.md" learning_capture_hook: "examples/hooks/bash/learning-capture.sh" # Anti-patterns - vibe_coding_trap: "guide/learning-with-ai.md:87" + vibe_coding_trap: "guide/roles/learning-with-ai.md:87" vibe_coding_context_overload: 13097 vibe_coding_context_overload_source: "Jens Rusitschka, 'Vibe Coding, Level 2' (Jan 2026)" vibe_coding_phased_strategy: 13097 - # AI Traceability & Attribution (guide/ai-traceability.md) - Added 2026-01-24 - ai_traceability_guide: "guide/ai-traceability.md" - ai_traceability_why: "guide/ai-traceability.md:29" - ai_traceability_disclosure_spectrum: "guide/ai-traceability.md:64" - ai_traceability_co_authored_by: "guide/ai-traceability.md:98" - ai_traceability_assisted_by: "guide/ai-traceability.md:120" - ai_traceability_git_ai: "guide/ai-traceability.md:170" - ai_traceability_llvm_policy: "guide/ai-traceability.md:201" - ai_traceability_ghostty_policy: "guide/ai-traceability.md:236" - ai_traceability_fedora_policy: "guide/ai-traceability.md:261" - ai_traceability_promptpwnd: "guide/ai-traceability.md:501" - ai_traceability_implementation: "guide/ai-traceability.md:566" - ai_traceability_templates: "guide/ai-traceability.md:648" + # AI Traceability & Attribution (guide/ops/ai-traceability.md) - Added 2026-01-24 + ai_traceability_guide: "guide/ops/ai-traceability.md" + ai_traceability_why: "guide/ops/ai-traceability.md:29" + ai_traceability_disclosure_spectrum: "guide/ops/ai-traceability.md:64" + ai_traceability_co_authored_by: "guide/ops/ai-traceability.md:98" + ai_traceability_assisted_by: "guide/ops/ai-traceability.md:120" + ai_traceability_git_ai: "guide/ops/ai-traceability.md:170" + ai_traceability_llvm_policy: "guide/ops/ai-traceability.md:201" + ai_traceability_ghostty_policy: "guide/ops/ai-traceability.md:236" + ai_traceability_fedora_policy: "guide/ops/ai-traceability.md:261" + ai_traceability_promptpwnd: "guide/ops/ai-traceability.md:501" + ai_traceability_implementation: "guide/ops/ai-traceability.md:566" + ai_traceability_templates: "guide/ops/ai-traceability.md:648" # AI Disclosure Templates ai_disclosure_contributing: "examples/config/CONTRIBUTING-ai-disclosure.md" ai_disclosure_pr_template: "examples/config/PULL_REQUEST_TEMPLATE-ai.md" @@ -201,15 +201,15 @@ deep_dive: tts_voice_catalog: "examples/integrations/agent-vibes/voice-catalog.md" tts_troubleshooting: "examples/integrations/agent-vibes/troubleshooting.md" tts_workflow: "guide/workflows/tts-setup.md" - tts_ai_ecosystem: "guide/ai-ecosystem.md:1124" + tts_ai_ecosystem: "guide/ecosystem/ai-ecosystem.md:1124" tts_hook_example: "examples/hooks/bash/tts-selective.sh" tts_claude_md_template: "examples/claude-md/tts-enabled.md" - # Sandbox Isolation for Coding Agents (guide/sandbox-isolation.md) - Added 2026-01-31 - sandbox_isolation_guide: "guide/sandbox-isolation.md" - sandbox_isolation_decision_tree: "guide/sandbox-isolation.md:7" - sandbox_docker_sandboxes: "guide/sandbox-isolation.md:67" - sandbox_docker_network: "guide/sandbox-isolation.md:121" - sandbox_docker_templates: "guide/sandbox-isolation.md:165" + # Sandbox Isolation for Coding Agents (guide/security/sandbox-isolation.md) - Added 2026-01-31 + sandbox_isolation_guide: "guide/security/sandbox-isolation.md" + sandbox_isolation_decision_tree: "guide/security/sandbox-isolation.md:7" + sandbox_docker_sandboxes: "guide/security/sandbox-isolation.md:67" + sandbox_docker_network: "guide/security/sandbox-isolation.md:121" + sandbox_docker_templates: "guide/security/sandbox-isolation.md:165" sandbox_docker_docs: "https://docs.docker.com/ai/sandboxes/" sandbox_docker_claude_config: "https://docs.docker.com/ai/sandboxes/claude-code/" sandbox_docker_network_docs: "https://docs.docker.com/ai/sandboxes/network-policies/" @@ -218,26 +218,26 @@ deep_dive: sandbox_cloudflare_sdk: "https://developers.cloudflare.com/sandbox/tutorials/claude-code/" sandbox_vercel: "https://vercel.com/docs/vercel-sandbox/" sandbox_e2b: "https://e2b.dev" - sandbox_native_cc: "guide/architecture.md:606" + sandbox_native_cc: "guide/core/architecture.md:606" # Native Claude Code Sandbox (Official docs, v2.1.0+) - Added 2026-02-02 - sandbox_native_guide: "guide/sandbox-native.md" - sandbox_native_why: "guide/sandbox-native.md:47" # Why Native Sandboxing - sandbox_native_os_primitives: "guide/sandbox-native.md:68" # Seatbelt vs bubblewrap - sandbox_native_filesystem: "guide/sandbox-native.md:178" # Filesystem isolation - sandbox_native_network: "guide/sandbox-native.md:221" # Network proxy architecture - sandbox_native_modes: "guide/sandbox-native.md:7" # Auto-allow vs Regular - sandbox_native_escape_hatch: "guide/sandbox-native.md:341" # dangerouslyDisableSandbox - sandbox_native_security_limits: "guide/sandbox-native.md:396" # Domain fronting, Unix sockets - sandbox_native_opensource: "guide/sandbox-native.md:481" # Open-source runtime - sandbox_native_platforms: "guide/sandbox-native.md:505" # Platform support - sandbox_native_decision_tree: "guide/sandbox-native.md:517" # Native vs Docker - sandbox_native_config_examples: "guide/sandbox-native.md:564" # Configuration examples - sandbox_native_best_practices: "guide/sandbox-native.md:637" # Best practices - sandbox_native_troubleshooting: "guide/sandbox-native.md:650" # Troubleshooting + sandbox_native_guide: "guide/security/sandbox-native.md" + sandbox_native_why: "guide/security/sandbox-native.md:47" # Why Native Sandboxing + sandbox_native_os_primitives: "guide/security/sandbox-native.md:68" # Seatbelt vs bubblewrap + sandbox_native_filesystem: "guide/security/sandbox-native.md:178" # Filesystem isolation + sandbox_native_network: "guide/security/sandbox-native.md:221" # Network proxy architecture + sandbox_native_modes: "guide/security/sandbox-native.md:7" # Auto-allow vs Regular + sandbox_native_escape_hatch: "guide/security/sandbox-native.md:341" # dangerouslyDisableSandbox + sandbox_native_security_limits: "guide/security/sandbox-native.md:396" # Domain fronting, Unix sockets + sandbox_native_opensource: "guide/security/sandbox-native.md:481" # Open-source runtime + sandbox_native_platforms: "guide/security/sandbox-native.md:505" # Platform support + sandbox_native_decision_tree: "guide/security/sandbox-native.md:517" # Native vs Docker + sandbox_native_config_examples: "guide/security/sandbox-native.md:564" # Configuration examples + sandbox_native_best_practices: "guide/security/sandbox-native.md:637" # Best practices + sandbox_native_troubleshooting: "guide/security/sandbox-native.md:650" # Troubleshooting sandbox_runtime_oss: "https://github.com/anthropic-experimental/sandbox-runtime" sandbox_runtime_npm: "https://www.npmjs.com/package/@anthropic-ai/sandbox-runtime" sandbox_official_docs: "https://code.claude.com/docs/en/sandboxing" - sandbox_comparison_native_docker: "guide/sandbox-isolation.md:238" # Section 4 Native CC + sandbox_comparison_native_docker: "guide/security/sandbox-isolation.md:238" # Section 4 Native CC sandbox_native_evaluation: "docs/resource-evaluations/native-sandbox-official-docs.md" sandbox_native_score: "5/5" # Templates (Added 2026-02-02) @@ -246,25 +246,25 @@ deep_dive: sandbox_validation_hook: "examples/hooks/bash/sandbox-validation.sh" # Docker Sandboxes (existing) sandbox_evaluation: "docs/resource-evaluations/docker-sandboxes-isolation.md" - sandbox_safe_autonomy: "guide/sandbox-isolation.md:496" # Safe Autonomy Workflows - sandbox_anti_patterns: "guide/sandbox-isolation.md:546" # Anti-Patterns - sandbox_comparison_matrix: "guide/sandbox-isolation.md:477" # Comparison Matrix + sandbox_safe_autonomy: "guide/security/sandbox-isolation.md:496" # Safe Autonomy Workflows + sandbox_anti_patterns: "guide/security/sandbox-isolation.md:546" # Anti-Patterns + sandbox_comparison_matrix: "guide/security/sandbox-isolation.md:477" # Comparison Matrix sandbox_score: "4/5" - # Third-Party Tools (guide/third-party-tools.md) - Added 2026-02-01 - third_party_tools_guide: "guide/third-party-tools.md" - third_party_tools_cost_tracking: "guide/third-party-tools.md:42" - third_party_tools_rtk: "guide/third-party-tools.md:7" - third_party_tools_session_mgmt: "guide/third-party-tools.md:126" - third_party_tools_config_mgmt: "guide/third-party-tools.md:214" - third_party_tools_alternative_uis: "guide/third-party-tools.md:259" - third_party_tools_known_gaps: "guide/third-party-tools.md:375" - third_party_tools_recommendations: "guide/third-party-tools.md:391" + # Third-Party Tools (guide/ecosystem/third-party-tools.md) - Added 2026-02-01 + third_party_tools_guide: "guide/ecosystem/third-party-tools.md" + third_party_tools_cost_tracking: "guide/ecosystem/third-party-tools.md:42" + third_party_tools_rtk: "guide/ecosystem/third-party-tools.md:7" + third_party_tools_session_mgmt: "guide/ecosystem/third-party-tools.md:126" + third_party_tools_config_mgmt: "guide/ecosystem/third-party-tools.md:214" + third_party_tools_alternative_uis: "guide/ecosystem/third-party-tools.md:259" + third_party_tools_known_gaps: "guide/ecosystem/third-party-tools.md:375" + third_party_tools_recommendations: "guide/ecosystem/third-party-tools.md:391" third_party_ccusage: "https://www.npmjs.com/package/ccusage" third_party_ccusage_site: "https://ccusage.com" third_party_ccburn: "https://github.com/JuanjoFuchs/ccburn" third_party_straude: "https://straude.com" third_party_straude_npm: "https://www.npmjs.com/package/straude" - third_party_straude_guide: "guide/third-party-tools.md:92" + third_party_straude_guide: "guide/ecosystem/third-party-tools.md:92" third_party_straude_eval: "docs/resource-evaluations/straude-evaluation.md" third_party_claude_code_viewer: "https://www.npmjs.com/package/@kimuson/claude-code-viewer" third_party_claude_code_config: "https://github.com/joeyism/claude-code-config" @@ -309,18 +309,18 @@ deep_dive: permissions_deny_known_limitation: "background indexing may expose via system reminders before checks — GitHub #4160" permissions_deny_defense_in_depth: "store secrets outside project dir for guaranteed protection" # Visual Reference (ASCII diagrams) - visual_reference: "guide/visual-reference.md" - # Architecture internals (guide/architecture.md) - architecture_visual_overview: "guide/architecture.md:51" + visual_reference: "guide/core/visual-reference.md" + # Architecture internals (guide/core/architecture.md) + architecture_visual_overview: "guide/core/architecture.md:51" architecture_visual_source: "https://www.linkedin.com/posts/mohamed-ali-ben-salem-2b777b9a_en-ce-moment-je-vois-passer-des-posts-du-activity-7420592149110362112-eY5a" - architecture_master_loop: "guide/architecture.md:82" - architecture_tools: "guide/architecture.md:219" - architecture_context: "guide/architecture.md:312" - architecture_subagents: "guide/architecture.md:471" - architecture_permissions: "guide/architecture.md:541" - architecture_mcp: "guide/architecture.md:746" + architecture_master_loop: "guide/core/architecture.md:82" + architecture_tools: "guide/core/architecture.md:219" + architecture_context: "guide/core/architecture.md:312" + architecture_subagents: "guide/core/architecture.md:471" + architecture_permissions: "guide/core/architecture.md:541" + architecture_mcp: "guide/core/architecture.md:746" architecture_mcp_visual: "guide/images/mcp-architecture-diagram.svg" - architecture_philosophy: "guide/architecture.md:1205" + architecture_philosophy: "guide/core/architecture.md:1205" # Official LLM-Optimized Documentation - Added 2026-02-25 official_llms_index: "https://code.claude.com/docs/llms.txt" # Index ~65 pages, ~15-20K tokens — use first for discovery official_llms_full: "https://code.claude.com/docs/llms-full.txt" # Full doc ~98KB, ~25-30K tokens — source de vérité officielle @@ -328,9 +328,9 @@ deep_dive: system_prompts_official: "https://platform.claude.com/docs/en/release-notes/system-prompts" system_prompts_willison_analysis: "https://simonwillison.net/2025/May/25/claude-4-system-prompt/" system_prompts_prompthub: "https://www.prompthub.us/blog/an-analysis-of-the-claude-4-system-prompt" - system_prompts_architecture: "guide/architecture.md:360" + system_prompts_architecture: "guide/core/architecture.md:360" # MCP Apps Extension (SEP-1865) - Added 2026-01-27 - mcp_apps_architecture: "guide/architecture.md:753" + mcp_apps_architecture: "guide/core/architecture.md:753" mcp_apps_evolution: "guide/ultimate-guide.md:9252" mcp_apps_spec: "https://github.com/modelcontextprotocol/ext-apps" mcp_apps_blog_mcp: "https://blog.modelcontextprotocol.io/posts/2026-01-26-mcp-apps/" @@ -570,16 +570,16 @@ deep_dive: - "Linear MCP: ~9.5k installs (issue tracking)" plugins_awesome_list: "https://github.com/hesreallyhim/awesome-claude-code" plugins_awesome_list_stars: "20k+" - chain_of_verification: "guide/methodologies.md:230" + chain_of_verification: "guide/core/methodologies.md:230" chain_of_verification_paper: "https://arxiv.org/abs/2309.11495" chain_of_verification_acl: "https://aclanthology.org/2024.findings-acl.212/" # Verification Loops & Eval Harness (added 2026-01-23) - verification_loops: "guide/methodologies.md:245" + verification_loops: "guide/core/methodologies.md:245" verification_loops_source: "https://www.anthropic.com/engineering/claude-code-best-practices" - eval_harness: "guide/methodologies.md:289" + eval_harness: "guide/core/methodologies.md:289" eval_harness_source: "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents" # GSD (Get Shit Done) methodology (added 2026-01-25) - gsd_methodology: "guide/methodologies.md:53" + gsd_methodology: "guide/core/methodologies.md:53" gsd_evaluation: "docs/resource-evaluations/gsd-evaluation.md" gsd_source: "https://github.com/glittercowboy/get-shit-done" gsd_note: "Overlap with existing patterns (Ralph Loop, Gas Town, BMAD)" @@ -608,35 +608,35 @@ deep_dive: audit_agents_skills_industry_context: "29.5% deploy without evaluation (LangChain 2026), 18% cite agent bugs as top challenge" audit_agents_skills_guide_refs: "guide/ultimate-guide.md:4951 (after Agent Validation Checklist), guide/ultimate-guide.md:5495 (after Skill Validation)" # Practitioner Insights (external validation) - practitioner_insights: "guide/ai-ecosystem.md:2170" - practitioner_dave_van_veen: "guide/ai-ecosystem.md:2174" - practitioner_matteo_collina: "guide/ai-ecosystem.md:2203" + practitioner_insights: "guide/ecosystem/ai-ecosystem.md:2170" + practitioner_dave_van_veen: "guide/ecosystem/ai-ecosystem.md:2174" + practitioner_matteo_collina: "guide/ecosystem/ai-ecosystem.md:2203" # Outcome Engineering (o16g) - Emerging manifesto (2026-02-13) - outcome_engineering_o16g: "guide/ai-ecosystem.md:2366" + outcome_engineering_o16g: "guide/ecosystem/ai-ecosystem.md:2366" outcome_engineering_url: "https://o16g.com/" outcome_engineering_author: "Cory Ondrejka (CTO Onebrief, co-creator Second Life, ex-VP Google/Meta)" outcome_engineering_status: "Emerging - on watch list for community adoption" practitioner_collina_source: "https://adventures.nodeland.dev/archive/the-human-in-the-loop/" - practitioner_steinberger: "guide/ai-ecosystem.md:2242" + practitioner_steinberger: "guide/ecosystem/ai-ecosystem.md:2242" practitioner_steinberger_source: "https://steipete.me/posts/2025/shipping-at-inference-speed" - practitioner_addy_osmani: "guide/ai-ecosystem.md:2269" + practitioner_addy_osmani: "guide/ecosystem/ai-ecosystem.md:2269" practitioner_osmani_source: "https://addyo.substack.com/p/the-80-problem-in-agentic-coding" - practitioner_alan: "guide/ai-ecosystem.md:2299" + practitioner_alan: "guide/ecosystem/ai-ecosystem.md:2299" practitioner_alan_source: "https://www.linkedin.com/pulse/le-principe-de-la-tour-eiffel-et-ralph-wiggum-maxime-le-bras-psmxe/" - verification_paradox: "guide/production-safety.md:639" + verification_paradox: "guide/security/production-safety.md:639" verification_paradox_source: "https://www.linkedin.com/pulse/le-principe-de-la-tour-eiffel-et-ralph-wiggum-maxime-le-bras-psmxe/" - eighty_percent_problem: "guide/ai-ecosystem.md:2269" - comprehension_debt_secondary: "guide/ai-ecosystem.md:2269" # See also: vibe_coding_trap (primary) - # DevOps/SRE Guide (guide/devops-sre.md) - devops_sre_guide: "guide/devops-sre.md" - devops_fire_framework: "guide/devops-sre.md:46" - devops_k8s_troubleshooting: "guide/devops-sre.md:129" - devops_k8s_prompts: "guide/devops-sre.md:151" - devops_incident_response: "guide/devops-sre.md:333" - devops_iac_patterns: "guide/devops-sre.md:504" - devops_guardrails: "guide/devops-sre.md:687" - devops_limitations: "guide/devops-sre.md:297" - devops_quick_reference: "guide/devops-sre.md:794" + eighty_percent_problem: "guide/ecosystem/ai-ecosystem.md:2269" + comprehension_debt_secondary: "guide/ecosystem/ai-ecosystem.md:2269" # See also: vibe_coding_trap (primary) + # DevOps/SRE Guide (guide/ops/devops-sre.md) + devops_sre_guide: "guide/ops/devops-sre.md" + devops_fire_framework: "guide/ops/devops-sre.md:46" + devops_k8s_troubleshooting: "guide/ops/devops-sre.md:129" + devops_k8s_prompts: "guide/ops/devops-sre.md:151" + devops_incident_response: "guide/ops/devops-sre.md:333" + devops_iac_patterns: "guide/ops/devops-sre.md:504" + devops_guardrails: "guide/ops/devops-sre.md:687" + devops_limitations: "guide/ops/devops-sre.md:297" + devops_quick_reference: "guide/ops/devops-sre.md:794" devops_agent: "examples/agents/devops-sre.md" devops_claude_md: "examples/claude-md/devops-sre.md" # Product Designer (design-to-code workflow) @@ -749,19 +749,19 @@ deep_dive: author: "Steve Yegge" description: "Multi-agent workspace manager using Claude Code instances" status: "Experimental (Jan 2026)" - guide_section: "guide/ai-ecosystem.md:850" + guide_section: "guide/ecosystem/ai-ecosystem.md:850" multiclaude: repo: "https://github.com/dlorenc/multiclaude" author: "dlorenc" description: "Self-hosted multi-agent Claude Code spawner (tmux + git worktrees)" status: "Active development (Jan 2026, 383 stars)" - guide_section: "guide/ai-ecosystem.md:850" + guide_section: "guide/ecosystem/ai-ecosystem.md:850" agent_chat: repo: "https://github.com/justinabrahms/agent-chat" author: "Justin Abrahms" description: "Real-time monitoring UI for Gas Town and multiclaude (SSE + SQLite)" status: "Early preview (Jan 2026, v0.2.0)" - guide_section: "guide/ai-ecosystem.md:850" + guide_section: "guide/ecosystem/ai-ecosystem.md:850" # External research & alignment tools external_research: claude_constitution: @@ -771,7 +771,7 @@ deep_dive: description: "Claude's Constitutional AI framework - value hierarchy (safety > ethics > compliance > utility)" license: "CC0 1.0 (public domain)" published: "2026-01-21" - guide_section: "guide/data-privacy.md:296" + guide_section: "guide/security/data-privacy.md:296" petri_v2: repo: "https://github.com/safety-research/petri" blog: "https://alignment.anthropic.com/2026/petri-v2/" @@ -888,7 +888,7 @@ deep_dive: spec_osmani_score: "4/5" spec_task_granularity: "guide/workflows/spec-first.md:62" # Vertical slices + PRD checklist (Allan Hill, Feb 2026) spec_prd_checklist: "guide/workflows/spec-first.md:68" # 6-dimension PRD quality checklist - atdd_with_agents: "guide/methodologies.md:161" # ATDD + Gherkin for agentic workflows + atdd_with_agents: "guide/core/methodologies.md:161" # ATDD + Gherkin for agentic workflows commands_table: 47 shortcuts_table: 368 troubleshooting: 11311 @@ -900,23 +900,23 @@ deep_dive: ai_ecosystem_tool_matrix: 20031 ai_ecosystem_workflows: 20166 ai_ecosystem_integration: 20294 - ai_ecosystem_detailed: "guide/ai-ecosystem.md" - ai_ecosystem_goose: "guide/ai-ecosystem.md:2074" - ai_ecosystem_goose_comparison: "guide/ai-ecosystem.md:2090" - ai_ecosystem_context_packing: "guide/ai-ecosystem.md:2533" - ai_ecosystem_multi_ide_sync: "guide/ai-ecosystem.md:1282" - agents_md_support_status: "guide/ai-ecosystem.md:1348" - ai_ecosystem_build_vs_use: "guide/ai-ecosystem.md:2399" # Section 11.3 - When to Build vs Use (ADK, LangChain, Vercel AI SDK) + ai_ecosystem_detailed: "guide/ecosystem/ai-ecosystem.md" + ai_ecosystem_goose: "guide/ecosystem/ai-ecosystem.md:2074" + ai_ecosystem_goose_comparison: "guide/ecosystem/ai-ecosystem.md:2090" + ai_ecosystem_context_packing: "guide/ecosystem/ai-ecosystem.md:2533" + ai_ecosystem_multi_ide_sync: "guide/ecosystem/ai-ecosystem.md:1282" + agents_md_support_status: "guide/ecosystem/ai-ecosystem.md:1348" + ai_ecosystem_build_vs_use: "guide/ecosystem/ai-ecosystem.md:2399" # Section 11.3 - When to Build vs Use (ADK, LangChain, Vercel AI SDK) # Architecture Diagrams as Context (advanced pattern) - Added 2026-01-25 - architecture_diagrams_input: "guide/ai-ecosystem.md:2567" + architecture_diagrams_input: "guide/ecosystem/ai-ecosystem.md:2567" architecture_diagrams_mcp_tools: - "Archy MCP: https://www.pulsemcp.com/servers/phxdev1-archy" - "Mermaid MCP: 61.4K users" - "Blueprint MCP (ArcadeAI)" llm_oop_research: "https://dl.acm.org/doi/10.1145/3639474.3640052" architecture_diagrams_source: "https://www.linkedin.com/posts/tigraff_uml-claude-wibecoding-activity-7420595633826258944-gGO5" - ai_ecosystem_voice_to_text: "guide/ai-ecosystem.md:1066" - ai_ecosystem_alternative_providers: "guide/ai-ecosystem.md:2639" + ai_ecosystem_voice_to_text: "guide/ecosystem/ai-ecosystem.md:1066" + ai_ecosystem_alternative_providers: "guide/ecosystem/ai-ecosystem.md:2639" voice_refine_skill: "examples/skills/voice-refine/SKILL.md" # PR Triage Skill (added 2026-03-05) pr_triage_skill: "examples/skills/pr-triage/SKILL.md" @@ -946,7 +946,7 @@ deep_dive: cowork_faq: "https://github.com/FlorianBruniaux/claude-cowork-guide/blob/main/reference/faq.md" cowork_prompts: "https://github.com/FlorianBruniaux/claude-cowork-guide/tree/main/prompts" cowork_workflows: "https://github.com/FlorianBruniaux/claude-cowork-guide/tree/main/workflows" - cowork_section: "guide/ai-ecosystem.md:1809" + cowork_section: "guide/ecosystem/ai-ecosystem.md:1809" cowork_ultimate_guide: 20348 # Experimental Features teammatetool: 3976 @@ -986,25 +986,25 @@ deep_dive: workflow: 58 # Workflow (9 steps) fix: 11948 # Troubleshooting section architecture: 919 # Architecture internals - production_safety: "guide/production-safety.md" # Production safety rules - security_hardening: "guide/security-hardening.md" # Security best practices - security_cve_summary: "guide/security-hardening.md:15" # Decision Matrix + CVEs - security_supply_chain_stats: "guide/security-hardening.md:137" # Agent Skills Supply Chain Risks - security_mcp_scan_tool: "guide/security-hardening.md:32" # MCP Vetting Workflow - security_malicious_extensions: "guide/security-hardening.md:252" # .claude/ attack surface (§1.5) - security_kill_switch: "guide/security-hardening.md:630" # AI Kill Switch & Containment Architecture (§3.5) - security_claude_folder_audit: "guide/security-hardening.md:228" # Repository Pre-Scan (§1.4) + production_safety: "guide/security/production-safety.md" # Production safety rules + security_hardening: "guide/security/security-hardening.md" # Security best practices + security_cve_summary: "guide/security/security-hardening.md:15" # Decision Matrix + CVEs + security_supply_chain_stats: "guide/security/security-hardening.md:137" # Agent Skills Supply Chain Risks + security_mcp_scan_tool: "guide/security/security-hardening.md:32" # MCP Vetting Workflow + security_malicious_extensions: "guide/security/security-hardening.md:252" # .claude/ attack surface (§1.5) + security_kill_switch: "guide/security/security-hardening.md:630" # AI Kill Switch & Containment Architecture (§3.5) + security_claude_folder_audit: "guide/security/security-hardening.md:228" # Repository Pre-Scan (§1.4) security_toxicskills_evaluation: "docs/resource-evaluations/snyk-toxicskills-evaluation.md" security_check_command: "examples/commands/security-check.md" # Quick config check vs known threats security_audit_command: "examples/commands/security-audit.md" # Full 6-phase security audit (score /100) security_threat_db: "examples/commands/resources/threat-db.yaml" # Threat intelligence database (authors, skills, CVEs, patterns) security_update_threat_db: "examples/commands/update-threat-db.md" # /update-threat-db — research & update threat database - security_cc_scanner: "guide/security-hardening.md:780" # Claude Code Security (research preview) — Anthropic native vuln scanner, adversarial validation, patch suggestions + security_cc_scanner: "guide/security/security-hardening.md:780" # Claude Code Security (research preview) — Anthropic native vuln scanner, adversarial validation, patch suggestions security_patcher_agent: "examples/agents/security-patcher.md" # Agent: applies patches from security-auditor findings, human approval gate, Write/Edit tools security_gate_hook: "examples/hooks/bash/security-gate.sh" # PreToolUse hook: blocks 7 vuln patterns at write time (SQLi, XSS, hardcoded secrets, eval, weak hash, cmd injection, path traversal) - security_pr_review_workflow: "guide/security-hardening.md:712" # PR security review workflow — 3-agent pipeline, git hook integration + security_pr_review_workflow: "guide/security/security-hardening.md:712" # PR security review workflow — 3-agent pipeline, git hook integration agent_validation_checklist: 5744 # Agent validation section in ultimate-guide.md - git_mcp_guide: "guide/mcp-servers-ecosystem.md:113" # Git MCP server documentation + git_mcp_guide: "guide/ecosystem/mcp-servers-ecosystem.md:113" # Git MCP server documentation # ════════════════════════════════════════════════════════════════ # DECISION TREE (most important - en premier) @@ -1174,10 +1174,10 @@ mcp: playwright: "browser automation / E2E" figma: "design file access, tokens, structure (official)" git_mcp: "version control automation (official Anthropic) - 12 tools for commits, branches, diffs, logs" - git_mcp_guide: "guide/mcp-servers-ecosystem.md:102" + git_mcp_guide: "guide/ecosystem/mcp-servers-ecosystem.md:102" git_mcp_tools: "git_status, git_log, git_diff, git_commit, git_add, git_reset, git_branch, git_create_branch, git_checkout, git_show, git_diff_unstaged, git_diff_staged" git_mcp_install: "uvx mcp-server-git --repository /path/to/repo" - git_mcp_decision_matrix: "guide/mcp-servers-ecosystem.md:212" # Git MCP vs GitHub MCP vs Bash tool + git_mcp_decision_matrix: "guide/ecosystem/mcp-servers-ecosystem.md:212" # Git MCP vs GitHub MCP vs Bash tool git_mcp_repo: "https://github.com/modelcontextprotocol/servers/tree/main/src/git" git_mcp_score: "8.5/10" git_mcp_status: "Early development (API subject to change)" @@ -1192,7 +1192,7 @@ mcp: search_decision_tree: "grep (text) | ast-grep (structure) | Serena (symbols) | grepai (semantic)" search_tools_comparison: "guide/ultimate-guide.md:9845" search_tools_mastery_workflow: "guide/workflows/search-tools-mastery.md" - grep_vs_rag_history: "guide/architecture.md:232" + grep_vs_rag_history: "guide/core/architecture.md:232" ripgrep_native: "Grep tool (Claude Code built-in, ~20ms)" grepai_semantic: "Semantic search + call graph (Ollama-based, ~500ms)" grepai_benchmark: @@ -1208,10 +1208,10 @@ mcp: config: "~/.claude.json (mcpServers field) or .mcp.json (project root)" tool_search: "lazy loading MCP tools (v2.1.7+) - 85% token reduction - auto:N threshold config" tool_search_config: "ENABLE_TOOL_SEARCH=auto|auto:N|true|false" - tool_search_deep_dive: "guide/architecture.md:284" + tool_search_deep_dive: "guide/core/architecture.md:284" # ════════════════════════════════════════════════════════════════ -# ARCHITECTURE INTERNALS - see guide/architecture.md +# ARCHITECTURE INTERNALS - see guide/core/architecture.md # ════════════════════════════════════════════════════════════════ architecture: master_loop: "while(tool_call) - no DAG, no classifier, no RAG" @@ -1222,7 +1222,7 @@ architecture: philosophy: "less scaffolding, more model - trust Claude's reasoning" mcp_protocol: "JSON-RPC 2.0, treated as native tools" permissions: "interactive prompts + allow/deny rules + hooks" - deep_dive: "guide/architecture.md" + deep_dive: "guide/core/architecture.md" # ════════════════════════════════════════════════════════════════ # COST OPTIMIZATION - see deep_dive.cost_optimization @@ -1448,7 +1448,7 @@ ecosystem: focus: "Production-grade agentic coding guardrails (TDD, worktrees, manual commits)" academic: "Co-author 'Agentic Systems in Radiology' (ArXiv 2025)" alignment: "Validates patterns already documented in this guide" - guide_section: "guide/ai-ecosystem.md:1209" + guide_section: "guide/ecosystem/ai-ecosystem.md:1209" install_templates: "scripts/install-templates.sh" cowork: description: "Claude Code for non-developers (desktop app)" diff --git a/mcp-server/content/reference.yaml b/mcp-server/content/reference.yaml index 18d2225..347a57f 100644 --- a/mcp-server/content/reference.yaml +++ b/mcp-server/content/reference.yaml @@ -9,7 +9,7 @@ updated: "2026-02-26" # ════════════════════════════════════════════════════════════════ # DEEP DIVE - Line numbers in guide/ultimate-guide.md # Usage: Read file at line N for detailed documentation on topic -# For architecture internals, see guide/architecture.md +# For architecture internals, see guide/core/architecture.md # ════════════════════════════════════════════════════════════════ deep_dive: # Visual Diagrams Series (40 Mermaid diagrams) @@ -22,11 +22,11 @@ deep_dive: exploration_workflow: "guide/workflows/exploration-workflow.md" script_generation: "guide/workflows/iterative-refinement.md:200" anti_anchoring_prompts: "examples/semantic-anchors/anchor-catalog.md:248" - session_limits: "guide/architecture.md:442" + session_limits: "guide/core/architecture.md:442" claudemd_sizing: 3054 - scope_success_rates: "guide/adoption-approaches.md:26" + scope_success_rates: "guide/roles/adoption-approaches.md:26" # Claude Code Releases - claude_code_releases: "guide/claude-code-releases.md" + claude_code_releases: "guide/core/claude-code-releases.md" claude_code_releases_yaml: "machine-readable/claude-code-releases.yaml" # Code Review Automation (Pat Cullen, Jan 2026) review_pr_advanced: "examples/commands/review-pr.md:81" @@ -58,29 +58,29 @@ deep_dive: team_ai_instructions_token_savings: "59% context token reduction (measured, 5-dev team)" team_ai_instructions_threshold: "Team 5+ devs with multiple AI tools" # Known Issues & Critical Bugs (verified community reports) - known_issues: "guide/known-issues.md" - known_issues_github_bug: "guide/known-issues.md:7" # GitHub auto-creation bug - known_issues_token_consumption: "guide/known-issues.md:105" # Excessive token usage - known_issues_model_quality_aug2025: "guide/known-issues.md:197" # Resolved: Aug 2025 degradation + known_issues: "guide/core/known-issues.md" + known_issues_github_bug: "guide/core/known-issues.md:7" # GitHub auto-creation bug + known_issues_token_consumption: "guide/core/known-issues.md:105" # Excessive token usage + known_issues_model_quality_aug2025: "guide/core/known-issues.md:197" # Resolved: Aug 2025 degradation # Template Installation install_templates_script: "scripts/install-templates.sh" # Session management - session_search: "guide/observability.md:38" + session_search: "guide/ops/observability.md:38" session_search_script: "examples/scripts/session-search.sh" cc_sessions_script: "examples/scripts/cc-sessions.py" - session_resume_limitations: "guide/observability.md:126" - session_cross_folder_migration: "guide/observability.md:126" - session_migration_manual: "guide/observability.md:126" - session_migration_risks: "guide/observability.md:126" - session_migration_community_tool: "guide/observability.md:52" + session_resume_limitations: "guide/ops/observability.md:126" + session_cross_folder_migration: "guide/ops/observability.md:126" + session_migration_manual: "guide/ops/observability.md:126" + session_migration_risks: "guide/ops/observability.md:126" + session_migration_community_tool: "guide/ops/observability.md:52" session_migration_issue: "https://github.com/anthropics/claude-code/issues/1516" session_migration_weller_skill: "https://github.com/jimweller/dotfiles/tree/main/dotfiles/claude-code/skills/claude-migrate-session" # Activity monitoring - activity_monitoring: "guide/observability.md:467" # Tool call audit via JSONL - activity_monitoring_queries: "guide/observability.md:467" # jq queries for audit - activity_monitoring_alerts: "guide/observability.md:467" # Sensitive pattern detection - external_monitoring_tools: "guide/observability.md:527" # ccusage, claude-code-otel, Akto, MLflow, ccboard - proxying_claude_code: "guide/observability.md:699" # Proxyman, mitmproxy, ANTHROPIC_API_URL + activity_monitoring: "guide/ops/observability.md:467" # Tool call audit via JSONL + activity_monitoring_queries: "guide/ops/observability.md:467" # jq queries for audit + activity_monitoring_alerts: "guide/ops/observability.md:467" # Sensitive pattern detection + external_monitoring_tools: "guide/ops/observability.md:527" # ccusage, claude-code-otel, Akto, MLflow, ccboard + proxying_claude_code: "guide/ops/observability.md:699" # Proxyman, mitmproxy, ANTHROPIC_API_URL ccboard_activity_plan: "docs/resource-evaluations/ccboard-activity-module-plan.md" # Cost optimization - Local execution bridge bridge_script: "examples/scripts/bridge.py" @@ -91,7 +91,7 @@ deep_dive: rtk_website: "https://www.rtk-ai.app/" rtk_evaluation: "docs/resource-evaluations/rtk-evaluation.md" rtk_guide: "guide/ultimate-guide.md:14553" - rtk_third_party: "guide/third-party-tools.md:7" + rtk_third_party: "guide/ecosystem/third-party-tools.md:7" rtk_claude_md: "examples/claude-md/rtk-optimized.md" rtk_skill: "examples/skills/rtk-optimizer/SKILL.md" rtk_hook: "examples/hooks/bash/rtk-auto-wrapper.sh" @@ -100,7 +100,7 @@ deep_dive: rtk_score: "5/5" rtk_installation: "cargo install rtk or brew install rtk-ai/tap/rtk" # Google Antigravity (Agent-First IDE) - antigravity_guide: "guide/ai-ecosystem.md:1366" + antigravity_guide: "guide/ecosystem/ai-ecosystem.md:1366" antigravity_evaluation: "docs/resource-evaluations/google-antigravity-evaluation.md" antigravity_proxy: "https://www.npmjs.com/package/antigravity-claude-proxy" antigravity_codelabs: "https://codelabs.developers.google.com/getting-started-google-antigravity" @@ -125,35 +125,35 @@ deep_dive: talk_pipeline_patterns: "skill chaining + file-based state + tool permission scoping + human-in-the-loop gate + AI-to-AI handoff (Claude → Kimi)" talk_pipeline_checkpoint: "Stage 4 CHECKPOINT: user selects angle + title before script starts" talk_pipeline_kimi: "kimi.com (free) — copy-paste Stage 5 prompt for AI slide generation" - # reMarkable 2 + AI (guide/remarkable-ai.md) - remarkable_ai_guide: "guide/remarkable-ai.md" - remarkable_mcp_server: "guide/remarkable-ai.md#1-remarkable-mcp--le-game-changer" + # reMarkable 2 + AI (guide/ecosystem/remarkable-ai.md) + remarkable_ai_guide: "guide/ecosystem/remarkable-ai.md" + remarkable_mcp_server: "guide/ecosystem/remarkable-ai.md#1-remarkable-mcp--le-game-changer" remarkable_mcp_repo: "https://github.com/SamMorrowDrums/remarkable-mcp" - remarkable_ghostwriter: "guide/remarkable-ai.md#2-ghostwriter--interface-vision-llm" - remarkable_obsidian_sync: "guide/remarkable-ai.md#3-sync-remarkable--obsidian" - remarkable_ocr_pipeline: "guide/remarkable-ai.md#4-ocr--ai-pipeline-custom" - remarkable_ssh_tools: "guide/remarkable-ai.md#5-accès-ssh-et-outils-communautaires" - remarkable_meeting_workflow: "guide/remarkable-ai.md#10-meeting-notes--ai-summary" - remarkable_workflows_to_build: "guide/remarkable-ai.md#14-workflows-ai-augmentés-à-construire" - remarkable_getting_started: "guide/remarkable-ai.md#15-par-où-commencer" + remarkable_ghostwriter: "guide/ecosystem/remarkable-ai.md#2-ghostwriter--interface-vision-llm" + remarkable_obsidian_sync: "guide/ecosystem/remarkable-ai.md#3-sync-remarkable--obsidian" + remarkable_ocr_pipeline: "guide/ecosystem/remarkable-ai.md#4-ocr--ai-pipeline-custom" + remarkable_ssh_tools: "guide/ecosystem/remarkable-ai.md#5-accès-ssh-et-outils-communautaires" + remarkable_meeting_workflow: "guide/ecosystem/remarkable-ai.md#10-meeting-notes--ai-summary" + remarkable_workflows_to_build: "guide/ecosystem/remarkable-ai.md#14-workflows-ai-augmentés-à-construire" + remarkable_getting_started: "guide/ecosystem/remarkable-ai.md#15-par-où-commencer" remarkable_community: "https://github.com/reHackable/awesome-reMarkable" # Whitepapers (FR + EN) — 9 focused whitepapers on Claude Code whitepapers_url: "https://www.florian.bruniaux.com/guides" whitepapers_fr: "whitepapers/fr/" # FR sources (Quarto .qmd) whitepapers_en: "whitepapers/en/" # EN sources (Quarto .qmd) whitepapers_topics: "foundations, prompting, customization, security, architecture, team, privacy, reference, agent-teams" - # Learning with AI (guide/learning-with-ai.md) - learning_quick_check: "guide/learning-with-ai.md:38" - learning_uval_protocol: "guide/learning-with-ai.md:218" - learning_claude_config: "guide/learning-with-ai.md:458" - learning_breaking_dependency: "guide/learning-with-ai.md:575" - learning_embracing_ai: "guide/learning-with-ai.md:623" - learning_30day_plan: "guide/learning-with-ai.md:815" - learning_red_flags: "guide/learning-with-ai.md:612" + # Learning with AI (guide/roles/learning-with-ai.md) + learning_quick_check: "guide/roles/learning-with-ai.md:38" + learning_uval_protocol: "guide/roles/learning-with-ai.md:218" + learning_claude_config: "guide/roles/learning-with-ai.md:458" + learning_breaking_dependency: "guide/roles/learning-with-ai.md:575" + learning_embracing_ai: "guide/roles/learning-with-ai.md:623" + learning_30day_plan: "guide/roles/learning-with-ai.md:815" + learning_red_flags: "guide/roles/learning-with-ai.md:612" # Productivity Research RCTs - productivity_rct_metr: "guide/learning-with-ai.md:925" # METR 2025: experienced devs 19% slower on large codebases despite perceiving 20% faster - productivity_rct_echoes: "guide/learning-with-ai.md:926" # Borg 2025: 30.7% faster (median), ~55.9% habitual users, no maintainability impact downstream - productivity_maintainability_empirical: "guide/learning-with-ai.md:926" # Empirical data on "AI code is unmaintainable" claim — blind RCT shows no significant difference + productivity_rct_metr: "guide/roles/learning-with-ai.md:925" # METR 2025: experienced devs 19% slower on large codebases despite perceiving 20% faster + productivity_rct_echoes: "guide/roles/learning-with-ai.md:926" # Borg 2025: 30.7% faster (median), ~55.9% habitual users, no maintainability impact downstream + productivity_maintainability_empirical: "guide/roles/learning-with-ai.md:926" # Empirical data on "AI code is unmaintainable" claim — blind RCT shows no significant difference trust_calibration_maintainability_nuance: "guide/ultimate-guide.md:1097" # Nuance: defect rates ≠ maintenance burden (Borg et al. 2025) learning_mode_template: "examples/claude-md/learning-mode.md" learn_quiz_command: "examples/commands/learn/quiz.md" @@ -161,23 +161,23 @@ deep_dive: learn_alternatives_command: "examples/commands/learn/alternatives.md" learning_capture_hook: "examples/hooks/bash/learning-capture.sh" # Anti-patterns - vibe_coding_trap: "guide/learning-with-ai.md:87" + vibe_coding_trap: "guide/roles/learning-with-ai.md:87" vibe_coding_context_overload: 13097 vibe_coding_context_overload_source: "Jens Rusitschka, 'Vibe Coding, Level 2' (Jan 2026)" vibe_coding_phased_strategy: 13097 - # AI Traceability & Attribution (guide/ai-traceability.md) - Added 2026-01-24 - ai_traceability_guide: "guide/ai-traceability.md" - ai_traceability_why: "guide/ai-traceability.md:29" - ai_traceability_disclosure_spectrum: "guide/ai-traceability.md:64" - ai_traceability_co_authored_by: "guide/ai-traceability.md:98" - ai_traceability_assisted_by: "guide/ai-traceability.md:120" - ai_traceability_git_ai: "guide/ai-traceability.md:170" - ai_traceability_llvm_policy: "guide/ai-traceability.md:201" - ai_traceability_ghostty_policy: "guide/ai-traceability.md:236" - ai_traceability_fedora_policy: "guide/ai-traceability.md:261" - ai_traceability_promptpwnd: "guide/ai-traceability.md:501" - ai_traceability_implementation: "guide/ai-traceability.md:566" - ai_traceability_templates: "guide/ai-traceability.md:648" + # AI Traceability & Attribution (guide/ops/ai-traceability.md) - Added 2026-01-24 + ai_traceability_guide: "guide/ops/ai-traceability.md" + ai_traceability_why: "guide/ops/ai-traceability.md:29" + ai_traceability_disclosure_spectrum: "guide/ops/ai-traceability.md:64" + ai_traceability_co_authored_by: "guide/ops/ai-traceability.md:98" + ai_traceability_assisted_by: "guide/ops/ai-traceability.md:120" + ai_traceability_git_ai: "guide/ops/ai-traceability.md:170" + ai_traceability_llvm_policy: "guide/ops/ai-traceability.md:201" + ai_traceability_ghostty_policy: "guide/ops/ai-traceability.md:236" + ai_traceability_fedora_policy: "guide/ops/ai-traceability.md:261" + ai_traceability_promptpwnd: "guide/ops/ai-traceability.md:501" + ai_traceability_implementation: "guide/ops/ai-traceability.md:566" + ai_traceability_templates: "guide/ops/ai-traceability.md:648" # AI Disclosure Templates ai_disclosure_contributing: "examples/config/CONTRIBUTING-ai-disclosure.md" ai_disclosure_pr_template: "examples/config/PULL_REQUEST_TEMPLATE-ai.md" @@ -187,15 +187,15 @@ deep_dive: tts_voice_catalog: "examples/integrations/agent-vibes/voice-catalog.md" tts_troubleshooting: "examples/integrations/agent-vibes/troubleshooting.md" tts_workflow: "guide/workflows/tts-setup.md" - tts_ai_ecosystem: "guide/ai-ecosystem.md:1124" + tts_ai_ecosystem: "guide/ecosystem/ai-ecosystem.md:1124" tts_hook_example: "examples/hooks/bash/tts-selective.sh" tts_claude_md_template: "examples/claude-md/tts-enabled.md" - # Sandbox Isolation for Coding Agents (guide/sandbox-isolation.md) - Added 2026-01-31 - sandbox_isolation_guide: "guide/sandbox-isolation.md" - sandbox_isolation_decision_tree: "guide/sandbox-isolation.md:7" - sandbox_docker_sandboxes: "guide/sandbox-isolation.md:67" - sandbox_docker_network: "guide/sandbox-isolation.md:121" - sandbox_docker_templates: "guide/sandbox-isolation.md:165" + # Sandbox Isolation for Coding Agents (guide/security/sandbox-isolation.md) - Added 2026-01-31 + sandbox_isolation_guide: "guide/security/sandbox-isolation.md" + sandbox_isolation_decision_tree: "guide/security/sandbox-isolation.md:7" + sandbox_docker_sandboxes: "guide/security/sandbox-isolation.md:67" + sandbox_docker_network: "guide/security/sandbox-isolation.md:121" + sandbox_docker_templates: "guide/security/sandbox-isolation.md:165" sandbox_docker_docs: "https://docs.docker.com/ai/sandboxes/" sandbox_docker_claude_config: "https://docs.docker.com/ai/sandboxes/claude-code/" sandbox_docker_network_docs: "https://docs.docker.com/ai/sandboxes/network-policies/" @@ -204,26 +204,26 @@ deep_dive: sandbox_cloudflare_sdk: "https://developers.cloudflare.com/sandbox/tutorials/claude-code/" sandbox_vercel: "https://vercel.com/docs/vercel-sandbox/" sandbox_e2b: "https://e2b.dev" - sandbox_native_cc: "guide/architecture.md:606" + sandbox_native_cc: "guide/core/architecture.md:606" # Native Claude Code Sandbox (Official docs, v2.1.0+) - Added 2026-02-02 - sandbox_native_guide: "guide/sandbox-native.md" - sandbox_native_why: "guide/sandbox-native.md:47" # Why Native Sandboxing - sandbox_native_os_primitives: "guide/sandbox-native.md:68" # Seatbelt vs bubblewrap - sandbox_native_filesystem: "guide/sandbox-native.md:178" # Filesystem isolation - sandbox_native_network: "guide/sandbox-native.md:221" # Network proxy architecture - sandbox_native_modes: "guide/sandbox-native.md:7" # Auto-allow vs Regular - sandbox_native_escape_hatch: "guide/sandbox-native.md:341" # dangerouslyDisableSandbox - sandbox_native_security_limits: "guide/sandbox-native.md:396" # Domain fronting, Unix sockets - sandbox_native_opensource: "guide/sandbox-native.md:481" # Open-source runtime - sandbox_native_platforms: "guide/sandbox-native.md:505" # Platform support - sandbox_native_decision_tree: "guide/sandbox-native.md:517" # Native vs Docker - sandbox_native_config_examples: "guide/sandbox-native.md:564" # Configuration examples - sandbox_native_best_practices: "guide/sandbox-native.md:637" # Best practices - sandbox_native_troubleshooting: "guide/sandbox-native.md:650" # Troubleshooting + sandbox_native_guide: "guide/security/sandbox-native.md" + sandbox_native_why: "guide/security/sandbox-native.md:47" # Why Native Sandboxing + sandbox_native_os_primitives: "guide/security/sandbox-native.md:68" # Seatbelt vs bubblewrap + sandbox_native_filesystem: "guide/security/sandbox-native.md:178" # Filesystem isolation + sandbox_native_network: "guide/security/sandbox-native.md:221" # Network proxy architecture + sandbox_native_modes: "guide/security/sandbox-native.md:7" # Auto-allow vs Regular + sandbox_native_escape_hatch: "guide/security/sandbox-native.md:341" # dangerouslyDisableSandbox + sandbox_native_security_limits: "guide/security/sandbox-native.md:396" # Domain fronting, Unix sockets + sandbox_native_opensource: "guide/security/sandbox-native.md:481" # Open-source runtime + sandbox_native_platforms: "guide/security/sandbox-native.md:505" # Platform support + sandbox_native_decision_tree: "guide/security/sandbox-native.md:517" # Native vs Docker + sandbox_native_config_examples: "guide/security/sandbox-native.md:564" # Configuration examples + sandbox_native_best_practices: "guide/security/sandbox-native.md:637" # Best practices + sandbox_native_troubleshooting: "guide/security/sandbox-native.md:650" # Troubleshooting sandbox_runtime_oss: "https://github.com/anthropic-experimental/sandbox-runtime" sandbox_runtime_npm: "https://www.npmjs.com/package/@anthropic-ai/sandbox-runtime" sandbox_official_docs: "https://code.claude.com/docs/en/sandboxing" - sandbox_comparison_native_docker: "guide/sandbox-isolation.md:238" # Section 4 Native CC + sandbox_comparison_native_docker: "guide/security/sandbox-isolation.md:238" # Section 4 Native CC sandbox_native_evaluation: "docs/resource-evaluations/native-sandbox-official-docs.md" sandbox_native_score: "5/5" # Templates (Added 2026-02-02) @@ -232,19 +232,19 @@ deep_dive: sandbox_validation_hook: "examples/hooks/bash/sandbox-validation.sh" # Docker Sandboxes (existing) sandbox_evaluation: "docs/resource-evaluations/docker-sandboxes-isolation.md" - sandbox_safe_autonomy: "guide/sandbox-isolation.md:496" # Safe Autonomy Workflows - sandbox_anti_patterns: "guide/sandbox-isolation.md:546" # Anti-Patterns - sandbox_comparison_matrix: "guide/sandbox-isolation.md:477" # Comparison Matrix + sandbox_safe_autonomy: "guide/security/sandbox-isolation.md:496" # Safe Autonomy Workflows + sandbox_anti_patterns: "guide/security/sandbox-isolation.md:546" # Anti-Patterns + sandbox_comparison_matrix: "guide/security/sandbox-isolation.md:477" # Comparison Matrix sandbox_score: "4/5" - # Third-Party Tools (guide/third-party-tools.md) - Added 2026-02-01 - third_party_tools_guide: "guide/third-party-tools.md" - third_party_tools_cost_tracking: "guide/third-party-tools.md:42" - third_party_tools_rtk: "guide/third-party-tools.md:7" - third_party_tools_session_mgmt: "guide/third-party-tools.md:126" - third_party_tools_config_mgmt: "guide/third-party-tools.md:214" - third_party_tools_alternative_uis: "guide/third-party-tools.md:259" - third_party_tools_known_gaps: "guide/third-party-tools.md:375" - third_party_tools_recommendations: "guide/third-party-tools.md:391" + # Third-Party Tools (guide/ecosystem/third-party-tools.md) - Added 2026-02-01 + third_party_tools_guide: "guide/ecosystem/third-party-tools.md" + third_party_tools_cost_tracking: "guide/ecosystem/third-party-tools.md:42" + third_party_tools_rtk: "guide/ecosystem/third-party-tools.md:7" + third_party_tools_session_mgmt: "guide/ecosystem/third-party-tools.md:126" + third_party_tools_config_mgmt: "guide/ecosystem/third-party-tools.md:214" + third_party_tools_alternative_uis: "guide/ecosystem/third-party-tools.md:259" + third_party_tools_known_gaps: "guide/ecosystem/third-party-tools.md:375" + third_party_tools_recommendations: "guide/ecosystem/third-party-tools.md:391" third_party_ccusage: "https://www.npmjs.com/package/ccusage" third_party_ccusage_site: "https://ccusage.com" third_party_ccburn: "https://github.com/JuanjoFuchs/ccburn" @@ -291,18 +291,18 @@ deep_dive: permissions_deny_known_limitation: "background indexing may expose via system reminders before checks — GitHub #4160" permissions_deny_defense_in_depth: "store secrets outside project dir for guaranteed protection" # Visual Reference (ASCII diagrams) - visual_reference: "guide/visual-reference.md" - # Architecture internals (guide/architecture.md) - architecture_visual_overview: "guide/architecture.md:51" + visual_reference: "guide/core/visual-reference.md" + # Architecture internals (guide/core/architecture.md) + architecture_visual_overview: "guide/core/architecture.md:51" architecture_visual_source: "https://www.linkedin.com/posts/mohamed-ali-ben-salem-2b777b9a_en-ce-moment-je-vois-passer-des-posts-du-activity-7420592149110362112-eY5a" - architecture_master_loop: "guide/architecture.md:82" - architecture_tools: "guide/architecture.md:219" - architecture_context: "guide/architecture.md:312" - architecture_subagents: "guide/architecture.md:471" - architecture_permissions: "guide/architecture.md:541" - architecture_mcp: "guide/architecture.md:746" + architecture_master_loop: "guide/core/architecture.md:82" + architecture_tools: "guide/core/architecture.md:219" + architecture_context: "guide/core/architecture.md:312" + architecture_subagents: "guide/core/architecture.md:471" + architecture_permissions: "guide/core/architecture.md:541" + architecture_mcp: "guide/core/architecture.md:746" architecture_mcp_visual: "guide/images/mcp-architecture-diagram.svg" - architecture_philosophy: "guide/architecture.md:1205" + architecture_philosophy: "guide/core/architecture.md:1205" # Official LLM-Optimized Documentation - Added 2026-02-25 official_llms_index: "https://code.claude.com/docs/llms.txt" # Index ~65 pages, ~15-20K tokens — use first for discovery official_llms_full: "https://code.claude.com/docs/llms-full.txt" # Full doc ~98KB, ~25-30K tokens — source de vérité officielle @@ -310,9 +310,9 @@ deep_dive: system_prompts_official: "https://platform.claude.com/docs/en/release-notes/system-prompts" system_prompts_willison_analysis: "https://simonwillison.net/2025/May/25/claude-4-system-prompt/" system_prompts_prompthub: "https://www.prompthub.us/blog/an-analysis-of-the-claude-4-system-prompt" - system_prompts_architecture: "guide/architecture.md:360" + system_prompts_architecture: "guide/core/architecture.md:360" # MCP Apps Extension (SEP-1865) - Added 2026-01-27 - mcp_apps_architecture: "guide/architecture.md:753" + mcp_apps_architecture: "guide/core/architecture.md:753" mcp_apps_evolution: "guide/ultimate-guide.md:9252" mcp_apps_spec: "https://github.com/modelcontextprotocol/ext-apps" mcp_apps_blog_mcp: "https://blog.modelcontextprotocol.io/posts/2026-01-26-mcp-apps/" @@ -534,16 +534,16 @@ deep_dive: - "Linear MCP: ~9.5k installs (issue tracking)" plugins_awesome_list: "https://github.com/hesreallyhim/awesome-claude-code" plugins_awesome_list_stars: "20k+" - chain_of_verification: "guide/methodologies.md:230" + chain_of_verification: "guide/core/methodologies.md:230" chain_of_verification_paper: "https://arxiv.org/abs/2309.11495" chain_of_verification_acl: "https://aclanthology.org/2024.findings-acl.212/" # Verification Loops & Eval Harness (added 2026-01-23) - verification_loops: "guide/methodologies.md:245" + verification_loops: "guide/core/methodologies.md:245" verification_loops_source: "https://www.anthropic.com/engineering/claude-code-best-practices" - eval_harness: "guide/methodologies.md:289" + eval_harness: "guide/core/methodologies.md:289" eval_harness_source: "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents" # GSD (Get Shit Done) methodology (added 2026-01-25) - gsd_methodology: "guide/methodologies.md:53" + gsd_methodology: "guide/core/methodologies.md:53" gsd_evaluation: "docs/resource-evaluations/gsd-evaluation.md" gsd_source: "https://github.com/glittercowboy/get-shit-done" gsd_note: "Overlap with existing patterns (Ralph Loop, Gas Town, BMAD)" @@ -572,35 +572,35 @@ deep_dive: audit_agents_skills_industry_context: "29.5% deploy without evaluation (LangChain 2026), 18% cite agent bugs as top challenge" audit_agents_skills_guide_refs: "guide/ultimate-guide.md:4951 (after Agent Validation Checklist), guide/ultimate-guide.md:5495 (after Skill Validation)" # Practitioner Insights (external validation) - practitioner_insights: "guide/ai-ecosystem.md:2170" - practitioner_dave_van_veen: "guide/ai-ecosystem.md:2174" - practitioner_matteo_collina: "guide/ai-ecosystem.md:2203" + practitioner_insights: "guide/ecosystem/ai-ecosystem.md:2170" + practitioner_dave_van_veen: "guide/ecosystem/ai-ecosystem.md:2174" + practitioner_matteo_collina: "guide/ecosystem/ai-ecosystem.md:2203" # Outcome Engineering (o16g) - Emerging manifesto (2026-02-13) - outcome_engineering_o16g: "guide/ai-ecosystem.md:2366" + outcome_engineering_o16g: "guide/ecosystem/ai-ecosystem.md:2366" outcome_engineering_url: "https://o16g.com/" outcome_engineering_author: "Cory Ondrejka (CTO Onebrief, co-creator Second Life, ex-VP Google/Meta)" outcome_engineering_status: "Emerging - on watch list for community adoption" practitioner_collina_source: "https://adventures.nodeland.dev/archive/the-human-in-the-loop/" - practitioner_steinberger: "guide/ai-ecosystem.md:2242" + practitioner_steinberger: "guide/ecosystem/ai-ecosystem.md:2242" practitioner_steinberger_source: "https://steipete.me/posts/2025/shipping-at-inference-speed" - practitioner_addy_osmani: "guide/ai-ecosystem.md:2269" + practitioner_addy_osmani: "guide/ecosystem/ai-ecosystem.md:2269" practitioner_osmani_source: "https://addyo.substack.com/p/the-80-problem-in-agentic-coding" - practitioner_alan: "guide/ai-ecosystem.md:2299" + practitioner_alan: "guide/ecosystem/ai-ecosystem.md:2299" practitioner_alan_source: "https://www.linkedin.com/pulse/le-principe-de-la-tour-eiffel-et-ralph-wiggum-maxime-le-bras-psmxe/" - verification_paradox: "guide/production-safety.md:639" + verification_paradox: "guide/security/production-safety.md:639" verification_paradox_source: "https://www.linkedin.com/pulse/le-principe-de-la-tour-eiffel-et-ralph-wiggum-maxime-le-bras-psmxe/" - eighty_percent_problem: "guide/ai-ecosystem.md:2269" - comprehension_debt_secondary: "guide/ai-ecosystem.md:2269" # See also: vibe_coding_trap (primary) - # DevOps/SRE Guide (guide/devops-sre.md) - devops_sre_guide: "guide/devops-sre.md" - devops_fire_framework: "guide/devops-sre.md:46" - devops_k8s_troubleshooting: "guide/devops-sre.md:129" - devops_k8s_prompts: "guide/devops-sre.md:151" - devops_incident_response: "guide/devops-sre.md:333" - devops_iac_patterns: "guide/devops-sre.md:504" - devops_guardrails: "guide/devops-sre.md:687" - devops_limitations: "guide/devops-sre.md:297" - devops_quick_reference: "guide/devops-sre.md:794" + eighty_percent_problem: "guide/ecosystem/ai-ecosystem.md:2269" + comprehension_debt_secondary: "guide/ecosystem/ai-ecosystem.md:2269" # See also: vibe_coding_trap (primary) + # DevOps/SRE Guide (guide/ops/devops-sre.md) + devops_sre_guide: "guide/ops/devops-sre.md" + devops_fire_framework: "guide/ops/devops-sre.md:46" + devops_k8s_troubleshooting: "guide/ops/devops-sre.md:129" + devops_k8s_prompts: "guide/ops/devops-sre.md:151" + devops_incident_response: "guide/ops/devops-sre.md:333" + devops_iac_patterns: "guide/ops/devops-sre.md:504" + devops_guardrails: "guide/ops/devops-sre.md:687" + devops_limitations: "guide/ops/devops-sre.md:297" + devops_quick_reference: "guide/ops/devops-sre.md:794" devops_agent: "examples/agents/devops-sre.md" devops_claude_md: "examples/claude-md/devops-sre.md" # Product Designer (design-to-code workflow) @@ -691,19 +691,19 @@ deep_dive: author: "Steve Yegge" description: "Multi-agent workspace manager using Claude Code instances" status: "Experimental (Jan 2026)" - guide_section: "guide/ai-ecosystem.md:850" + guide_section: "guide/ecosystem/ai-ecosystem.md:850" multiclaude: repo: "https://github.com/dlorenc/multiclaude" author: "dlorenc" description: "Self-hosted multi-agent Claude Code spawner (tmux + git worktrees)" status: "Active development (Jan 2026, 383 stars)" - guide_section: "guide/ai-ecosystem.md:850" + guide_section: "guide/ecosystem/ai-ecosystem.md:850" agent_chat: repo: "https://github.com/justinabrahms/agent-chat" author: "Justin Abrahms" description: "Real-time monitoring UI for Gas Town and multiclaude (SSE + SQLite)" status: "Early preview (Jan 2026, v0.2.0)" - guide_section: "guide/ai-ecosystem.md:850" + guide_section: "guide/ecosystem/ai-ecosystem.md:850" # External research & alignment tools external_research: claude_constitution: @@ -713,7 +713,7 @@ deep_dive: description: "Claude's Constitutional AI framework - value hierarchy (safety > ethics > compliance > utility)" license: "CC0 1.0 (public domain)" published: "2026-01-21" - guide_section: "guide/data-privacy.md:296" + guide_section: "guide/security/data-privacy.md:296" petri_v2: repo: "https://github.com/safety-research/petri" blog: "https://alignment.anthropic.com/2026/petri-v2/" @@ -830,7 +830,7 @@ deep_dive: spec_osmani_score: "4/5" spec_task_granularity: "guide/workflows/spec-first.md:62" # Vertical slices + PRD checklist (Allan Hill, Feb 2026) spec_prd_checklist: "guide/workflows/spec-first.md:68" # 6-dimension PRD quality checklist - atdd_with_agents: "guide/methodologies.md:161" # ATDD + Gherkin for agentic workflows + atdd_with_agents: "guide/core/methodologies.md:161" # ATDD + Gherkin for agentic workflows commands_table: 47 shortcuts_table: 368 troubleshooting: 11311 @@ -842,23 +842,23 @@ deep_dive: ai_ecosystem_tool_matrix: 20031 ai_ecosystem_workflows: 20166 ai_ecosystem_integration: 20294 - ai_ecosystem_detailed: "guide/ai-ecosystem.md" - ai_ecosystem_goose: "guide/ai-ecosystem.md:2074" - ai_ecosystem_goose_comparison: "guide/ai-ecosystem.md:2090" - ai_ecosystem_context_packing: "guide/ai-ecosystem.md:2533" - ai_ecosystem_multi_ide_sync: "guide/ai-ecosystem.md:1282" - agents_md_support_status: "guide/ai-ecosystem.md:1348" - ai_ecosystem_build_vs_use: "guide/ai-ecosystem.md:2399" # Section 11.3 - When to Build vs Use (ADK, LangChain, Vercel AI SDK) + ai_ecosystem_detailed: "guide/ecosystem/ai-ecosystem.md" + ai_ecosystem_goose: "guide/ecosystem/ai-ecosystem.md:2074" + ai_ecosystem_goose_comparison: "guide/ecosystem/ai-ecosystem.md:2090" + ai_ecosystem_context_packing: "guide/ecosystem/ai-ecosystem.md:2533" + ai_ecosystem_multi_ide_sync: "guide/ecosystem/ai-ecosystem.md:1282" + agents_md_support_status: "guide/ecosystem/ai-ecosystem.md:1348" + ai_ecosystem_build_vs_use: "guide/ecosystem/ai-ecosystem.md:2399" # Section 11.3 - When to Build vs Use (ADK, LangChain, Vercel AI SDK) # Architecture Diagrams as Context (advanced pattern) - Added 2026-01-25 - architecture_diagrams_input: "guide/ai-ecosystem.md:2567" + architecture_diagrams_input: "guide/ecosystem/ai-ecosystem.md:2567" architecture_diagrams_mcp_tools: - "Archy MCP: https://www.pulsemcp.com/servers/phxdev1-archy" - "Mermaid MCP: 61.4K users" - "Blueprint MCP (ArcadeAI)" llm_oop_research: "https://dl.acm.org/doi/10.1145/3639474.3640052" architecture_diagrams_source: "https://www.linkedin.com/posts/tigraff_uml-claude-wibecoding-activity-7420595633826258944-gGO5" - ai_ecosystem_voice_to_text: "guide/ai-ecosystem.md:1066" - ai_ecosystem_alternative_providers: "guide/ai-ecosystem.md:2639" + ai_ecosystem_voice_to_text: "guide/ecosystem/ai-ecosystem.md:1066" + ai_ecosystem_alternative_providers: "guide/ecosystem/ai-ecosystem.md:2639" voice_refine_skill: "examples/skills/voice-refine/SKILL.md" # Cowork documentation (v1.0 - migrated to dedicated repo) cowork_reference: "machine-readable/cowork-reference.yaml" # Dedicated YAML index (kept local) @@ -874,7 +874,7 @@ deep_dive: cowork_faq: "https://github.com/FlorianBruniaux/claude-cowork-guide/blob/main/reference/faq.md" cowork_prompts: "https://github.com/FlorianBruniaux/claude-cowork-guide/tree/main/prompts" cowork_workflows: "https://github.com/FlorianBruniaux/claude-cowork-guide/tree/main/workflows" - cowork_section: "guide/ai-ecosystem.md:1809" + cowork_section: "guide/ecosystem/ai-ecosystem.md:1809" cowork_ultimate_guide: 20348 # Experimental Features teammatetool: 3976 @@ -914,25 +914,25 @@ deep_dive: workflow: 58 # Workflow (9 steps) fix: 11948 # Troubleshooting section architecture: 919 # Architecture internals - production_safety: "guide/production-safety.md" # Production safety rules - security_hardening: "guide/security-hardening.md" # Security best practices - security_cve_summary: "guide/security-hardening.md:15" # Decision Matrix + CVEs - security_supply_chain_stats: "guide/security-hardening.md:137" # Agent Skills Supply Chain Risks - security_mcp_scan_tool: "guide/security-hardening.md:32" # MCP Vetting Workflow - security_malicious_extensions: "guide/security-hardening.md:252" # .claude/ attack surface (§1.5) - security_kill_switch: "guide/security-hardening.md:630" # AI Kill Switch & Containment Architecture (§3.5) - security_claude_folder_audit: "guide/security-hardening.md:228" # Repository Pre-Scan (§1.4) + production_safety: "guide/security/production-safety.md" # Production safety rules + security_hardening: "guide/security/security-hardening.md" # Security best practices + security_cve_summary: "guide/security/security-hardening.md:15" # Decision Matrix + CVEs + security_supply_chain_stats: "guide/security/security-hardening.md:137" # Agent Skills Supply Chain Risks + security_mcp_scan_tool: "guide/security/security-hardening.md:32" # MCP Vetting Workflow + security_malicious_extensions: "guide/security/security-hardening.md:252" # .claude/ attack surface (§1.5) + security_kill_switch: "guide/security/security-hardening.md:630" # AI Kill Switch & Containment Architecture (§3.5) + security_claude_folder_audit: "guide/security/security-hardening.md:228" # Repository Pre-Scan (§1.4) security_toxicskills_evaluation: "docs/resource-evaluations/snyk-toxicskills-evaluation.md" security_check_command: "examples/commands/security-check.md" # Quick config check vs known threats security_audit_command: "examples/commands/security-audit.md" # Full 6-phase security audit (score /100) security_threat_db: "examples/commands/resources/threat-db.yaml" # Threat intelligence database (authors, skills, CVEs, patterns) security_update_threat_db: "examples/commands/update-threat-db.md" # /update-threat-db — research & update threat database - security_cc_scanner: "guide/security-hardening.md:780" # Claude Code Security (research preview) — Anthropic native vuln scanner, adversarial validation, patch suggestions + security_cc_scanner: "guide/security/security-hardening.md:780" # Claude Code Security (research preview) — Anthropic native vuln scanner, adversarial validation, patch suggestions security_patcher_agent: "examples/agents/security-patcher.md" # Agent: applies patches from security-auditor findings, human approval gate, Write/Edit tools security_gate_hook: "examples/hooks/bash/security-gate.sh" # PreToolUse hook: blocks 7 vuln patterns at write time (SQLi, XSS, hardcoded secrets, eval, weak hash, cmd injection, path traversal) - security_pr_review_workflow: "guide/security-hardening.md:712" # PR security review workflow — 3-agent pipeline, git hook integration + security_pr_review_workflow: "guide/security/security-hardening.md:712" # PR security review workflow — 3-agent pipeline, git hook integration agent_validation_checklist: 5744 # Agent validation section in ultimate-guide.md - git_mcp_guide: "guide/mcp-servers-ecosystem.md:113" # Git MCP server documentation + git_mcp_guide: "guide/ecosystem/mcp-servers-ecosystem.md:113" # Git MCP server documentation # ════════════════════════════════════════════════════════════════ # DECISION TREE (most important - en premier) @@ -1102,10 +1102,10 @@ mcp: playwright: "browser automation / E2E" figma: "design file access, tokens, structure (official)" git_mcp: "version control automation (official Anthropic) - 12 tools for commits, branches, diffs, logs" - git_mcp_guide: "guide/mcp-servers-ecosystem.md:102" + git_mcp_guide: "guide/ecosystem/mcp-servers-ecosystem.md:102" git_mcp_tools: "git_status, git_log, git_diff, git_commit, git_add, git_reset, git_branch, git_create_branch, git_checkout, git_show, git_diff_unstaged, git_diff_staged" git_mcp_install: "uvx mcp-server-git --repository /path/to/repo" - git_mcp_decision_matrix: "guide/mcp-servers-ecosystem.md:212" # Git MCP vs GitHub MCP vs Bash tool + git_mcp_decision_matrix: "guide/ecosystem/mcp-servers-ecosystem.md:212" # Git MCP vs GitHub MCP vs Bash tool git_mcp_repo: "https://github.com/modelcontextprotocol/servers/tree/main/src/git" git_mcp_score: "8.5/10" git_mcp_status: "Early development (API subject to change)" @@ -1120,7 +1120,7 @@ mcp: search_decision_tree: "grep (text) | ast-grep (structure) | Serena (symbols) | grepai (semantic)" search_tools_comparison: "guide/ultimate-guide.md:9845" search_tools_mastery_workflow: "guide/workflows/search-tools-mastery.md" - grep_vs_rag_history: "guide/architecture.md:232" + grep_vs_rag_history: "guide/core/architecture.md:232" ripgrep_native: "Grep tool (Claude Code built-in, ~20ms)" grepai_semantic: "Semantic search + call graph (Ollama-based, ~500ms)" grepai_benchmark: @@ -1136,10 +1136,10 @@ mcp: config: "~/.claude.json (mcpServers field) or .mcp.json (project root)" tool_search: "lazy loading MCP tools (v2.1.7+) - 85% token reduction - auto:N threshold config" tool_search_config: "ENABLE_TOOL_SEARCH=auto|auto:N|true|false" - tool_search_deep_dive: "guide/architecture.md:284" + tool_search_deep_dive: "guide/core/architecture.md:284" # ════════════════════════════════════════════════════════════════ -# ARCHITECTURE INTERNALS - see guide/architecture.md +# ARCHITECTURE INTERNALS - see guide/core/architecture.md # ════════════════════════════════════════════════════════════════ architecture: master_loop: "while(tool_call) - no DAG, no classifier, no RAG" @@ -1150,7 +1150,7 @@ architecture: philosophy: "less scaffolding, more model - trust Claude's reasoning" mcp_protocol: "JSON-RPC 2.0, treated as native tools" permissions: "interactive prompts + allow/deny rules + hooks" - deep_dive: "guide/architecture.md" + deep_dive: "guide/core/architecture.md" # ════════════════════════════════════════════════════════════════ # COST OPTIMIZATION - see deep_dive.cost_optimization @@ -1346,7 +1346,7 @@ ecosystem: focus: "Production-grade agentic coding guardrails (TDD, worktrees, manual commits)" academic: "Co-author 'Agentic Systems in Radiology' (ArXiv 2025)" alignment: "Validates patterns already documented in this guide" - guide_section: "guide/ai-ecosystem.md:1209" + guide_section: "guide/ecosystem/ai-ecosystem.md:1209" install_templates: "scripts/install-templates.sh" cowork: description: "Claude Code for non-developers (desktop app)" diff --git a/tools/audit-prompt.md b/tools/audit-prompt.md index a62e1a7..a04562b 100644 --- a/tools/audit-prompt.md +++ b/tools/audit-prompt.md @@ -606,7 +606,7 @@ Here's an example of what the audit report looks like: ## 8. Related Resources - [The Ultimate Claude Code Guide](../guide/ultimate-guide.md) - Full reference -- [Architecture & Internals](../guide/architecture.md) - How Claude Code works +- [Architecture & Internals](../guide/core/architecture.md) - How Claude Code works - [Cheatsheet](../guide/cheatsheet.md) - Quick daily reference - [Claude Code Official Docs](https://docs.anthropic.com/en/docs/claude-code) - Anthropic documentation diff --git a/tools/onboarding-prompt.md b/tools/onboarding-prompt.md index f77d065..d3425cc 100644 --- a/tools/onboarding-prompt.md +++ b/tools/onboarding-prompt.md @@ -271,7 +271,7 @@ Based on time spent and topics covered: - Everything shared with Claude Code is sent to Anthropic servers - Default retention: **5 years** (training enabled) - Action: [Disable training](https://claude.ai/settings/data-privacy-controls) → reduces to 30 days -- Details: [Data Privacy Guide](https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/data-privacy.md) +- Details: [Data Privacy Guide](https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/data-privacy.md) ## Output Format