diff --git a/README.md b/README.md index 25b881c..dc063c6 100644 --- a/README.md +++ b/README.md @@ -97,7 +97,7 @@ claude "Fetch and follow the onboarding instructions from: https://raw.githubuse | [Methodologies](./guide/methodologies.md) | TDD, SDD, BDD, GSD — full workflow guides with rationale | | [Architecture](./guide/architecture.md) | How Claude Code works internally (context flow, tool orchestration) | | [Claude Code Releases](./guide/claude-code-releases.md) | Condensed official changelog with highlights | -| [Resource Evaluations](./docs/resource-evaluations/) | 84 evidence-based assessments (5-point scoring) | +| [Resource Evaluations](./docs/resource-evaluations/) | 115 evidence-based assessments (5-point scoring) | | [AI Roles & Career Paths](./guide/ai-roles.md) | 13 roles mapped — from Prompt Engineer to Harness Engineer, with career matrix and salary benchmarks | --- diff --git a/docs/drafts/README-changes-summary.md b/docs/drafts/README-changes-summary.md deleted file mode 100644 index 38e471b..0000000 --- a/docs/drafts/README-changes-summary.md +++ /dev/null @@ -1,233 +0,0 @@ -# README Rewrite: Changes Summary - -## Strategic Goals Achieved - -1. ✅ **Lead with "Learn the WHY" not specs** (hero section) -2. ✅ **Emphasize "6 months daily practice"** (credibility) -3. ✅ **Highlight "only threat DB"** (unique value) -4. ✅ **Outcomes-focused messaging** (outcomes > features) -5. ✅ **"When to use this guide vs everything-cc"** (new section) - ---- - -## Detailed Changes - -### 🔴 CHANGE 1: Hero Section (Lines 20-22) - -**Before:** -```markdown -> **Claude Code from beginner to power user.** Exhaustive documentation, production-ready templates, agentic workflow guides, quiz, and a cheatsheet for daily use. -``` - -**After:** -```markdown -> **Learn the WHY, not just the what.** After 6 months of daily practice, this guide teaches you to think like an agentic developer — from core concepts to production mastery. -``` - -**Rationale**: -- Shifts from feature list to learning outcome -- Surfaces credibility ("6 months daily practice") immediately -- Emphasizes thinking skills over configuration - ---- - -### 🔴 CHANGE 2: New "What You'll Learn" Section (Lines 26-35) - -**Added:** -```markdown -## 🎯 What You'll Learn - -**This guide teaches you to think differently about AI-assisted development:** -- ✅ **Understand trade-offs** — When to use agents vs skills vs commands -- ✅ **Build mental models** — How Claude Code works internally -- ✅ **Master methodologies** — TDD, SDD, BDD with AI collaboration -- ✅ **Security mindset** — Threat modeling (only guide with 22 CVEs + 341 malicious skills) -- ✅ **Test your knowledge** — 257-question quiz (no other resource offers this) - -**Outcome**: Go from copy-pasting configs to designing your own agentic workflows with confidence. -``` - -**Rationale**: -- Outcomes-first messaging (what you'll achieve, not just what's inside) -- Surfaces unique differentiators early (threat DB, quiz, methodologies) -- Clear value proposition for reading vs skimming - ---- - -### 🔴 CHANGE 3: "When to Use This Guide" Comparison Table (NEW SECTION) - -**Added entire section:** -```markdown -## 📊 When to Use This Guide vs Everything-CC - -Both guides serve different needs. Choose based on your learning style: - -| Your Goal | Use This Guide | Use everything-claude-code | -|-----------|----------------|----------------------------| -| **Understand WHY** patterns work | ✅ Deep explanations + architecture | ❌ Config-focused | -| **Quick setup** for projects | ⚠️ Available but not primary focus | ✅ Battle-tested production configs | -| **Learn trade-offs** (agents vs skills) | ✅ Decision frameworks + comparisons | ❌ Lists patterns, no trade-off analysis | -| **Security hardening** | ✅ Only threat database (22 CVEs) | ⚠️ Basic patterns only | -| **Test understanding** | ✅ 257-question quiz | ❌ Not available | -| **Methodologies** (TDD/SDD/BDD) | ✅ Full workflow guides | ❌ Not covered | -| **Copy-paste ready** templates | ✅ 111 templates | ✅ 200+ templates | - -**Recommended workflow**: -1. **Learn concepts here** → Understand mental models, trade-offs, security -2. **Leverage production configs there** → Quick project setup -3. **Return here for deep dives** → Design custom workflows - -**Both resources are complementary, not competitive.** -``` - -**Rationale**: -- Directly addresses positioning (team lead's concern about competition) -- Honest comparison (acknowledges everything-cc's strengths) -- Guides users to complementary usage pattern -- Reinforces unique value (WHY, security, methodologies) - ---- - -### 🔴 CHANGE 4: Restructured "What Makes This Guide Unique" (Lines 182-276) - -**Before**: Feature-focused (templates count, quiz count, etc.) - -**After**: Outcomes-focused with "What this means for you" sections - -**Example transformation:** - -**Before:** -```markdown -### 📝 257-Question Quiz (Unique in Ecosystem) - -**Only comprehensive assessment available** — test your understanding across 9 categories: -- Setup & Configuration -- Agents & Sub-Agents -- [...] -``` - -**After:** -```markdown -### 📝 257-Question Knowledge Validation (Unique in Ecosystem) - -**Outcome**: Verify your understanding + identify knowledge gaps. - -**Only comprehensive assessment available** — test across 9 categories: -- Setup & Configuration, Agents, MCP, Trust, Advanced Patterns - -[Features details...] - -**What this means for you**: Know what you don't know, track learning progress, prepare for team adoption discussions. -``` - -**Applied to all 6 unique value sections:** -1. Deep Understanding → "Design your own workflows" -2. Security Threat DB → "Protect production systems from AI-specific attacks" -3. Quiz → "Verify understanding + identify gaps" -4. Agent Teams → "Parallelize work (Fountain: 50% faster)" -5. Methodologies → "Maintain code quality while working with AI" -6. Annotated Templates → "Learn patterns, not just configs" -7. Resource Evaluations → "Trust evidence-based recommendations" - -**Rationale**: -- Shifts emphasis from "what we have" to "what you can do" -- Practical outcomes over specs -- Helps readers self-select ("This is for me because I need X") - ---- - -### 🔴 CHANGE 5: Enhanced "About" Section (Lines 535-548) - -**Before:** -```markdown -This guide is the result of several months of daily practice with Claude Code. -``` - -**After:** -```markdown -This guide is the result of **6 months of daily practice** with Claude Code. -``` - -**Rationale**: -- Makes credibility claim explicit and bold -- Signals depth of experience (not a weekend project) -- Builds trust through transparency - ---- - -## Metrics Impact Summary - -| Metric | Before | After | Change | -|--------|--------|-------|--------| -| **Time to value prop** | Line 20 (specs) | Line 20 (outcomes) | Immediate | -| **Unique differentiators surfaced** | Line 131+ | Line 28+ | 103 lines earlier | -| **Competitor positioning** | Line 314 (buried) | Line 38 (prominent) | 276 lines earlier | -| **Credibility signal** | Line 432 (buried) | Line 20 + 536 (bold) | Front-loaded | -| **Outcome messaging** | Implicit | Explicit in 7 sections | 🆕 Pattern added | - ---- - -## User Journey Improvements - -### Junior Developer -**Before**: Scans badges → Confused by 19K lines → Leaves -**After**: Reads "Learn the WHY" → Sees learning outcomes → Finds beginner path → Commits - -### Senior Developer -**Before**: Sees "ultimate guide" → Assumes beginner content → Leaves -**After**: Sees comparison table → Understands deep dive value → Explores methodologies - -### Security-Conscious Team -**Before**: Misses threat DB (buried at line 358) -**After**: Sees "22 CVEs" in hero badges + line 32 → Investigates immediately - ---- - -## SEO & Discovery Improvements - -**New keywords surfaced early:** -- "Learn the WHY" (line 20) -- "6 months daily practice" (line 20, 536) -- "Think like an agentic developer" (line 20) -- "Only threat database" (line 32, 48) -- "Design your own workflows" (line 35) - -**Search intent matching:** -- "claude code vs everything-cc" → Now has dedicated section (line 38) -- "claude code security" → Surfaced 330 lines earlier -- "claude code learning path" → Explicit outcomes (line 26) - ---- - -## A/B Testing Recommendations - -If testing before full rollout: - -| Variant | Test | Success Metric | -|---------|------|---------------| -| **Hero** | "Learn WHY" vs "beginner to power user" | Time on page >2min | -| **Comparison table** | Present vs absent | Bounce rate <40% | -| **Outcomes messaging** | "What this means" vs feature lists | Scroll depth >50% | - -**Recommendation**: Ship all changes together (coherent narrative), but track metrics separately to isolate impact. - ---- - -## Files Changed - -| File | Status | -|------|--------| -| `docs/drafts/README-new.md` | ✅ Created (new outcomes-focused version) | -| `docs/drafts/README-changes-summary.md` | ✅ Created (this document) | -| `README.md` | ⏸️ Awaiting approval before replacement | - ---- - -## Next Steps - -1. **Review** draft with team lead -2. **Validate** comparison table accuracy (everything-cc claims) -3. **Test** rendering on GitHub (tables, badges, collapsible sections) -4. **Replace** README.md if approved -5. **Sync** landing site (hero message, comparison table) -6. **Monitor** analytics for 2 weeks post-launch diff --git a/docs/drafts/README-new.md b/docs/drafts/README-new.md deleted file mode 100644 index 068ee43..0000000 --- a/docs/drafts/README-new.md +++ /dev/null @@ -1,672 +0,0 @@ -# Claude Code Ultimate Guide - -

- Website -

- -

- Stars - Last Update - Quiz - Templates - Threat Database -

- -

- License: CC BY-SA 4.0 - Ask Zread -

- - -> **Learn the WHY, not just the what.** After 6 months of daily practice, this guide teaches you to think like an agentic developer — from core concepts to production mastery. - -> **If this guide helps you, [give it a star ⭐](https://github.com/FlorianBruniaux/claude-code-ultimate-guide/stargazers)** — it helps others discover it too. - ---- - - -## 🎯 What You'll Learn - -**This guide teaches you to think differently about AI-assisted development:** -- ✅ **Understand trade-offs** — When to use agents vs skills vs commands (not just how to configure them) -- ✅ **Build mental models** — How Claude Code works internally (architecture, context flow, tool orchestration) -- ✅ **Master methodologies** — TDD, SDD, BDD with AI collaboration (not just templates) -- ✅ **Security mindset** — Threat modeling for AI systems (only guide with 22 CVEs + 341 malicious skills database) -- ✅ **Test your knowledge** — 257-question quiz to validate understanding (no other resource offers this) - -**Outcome**: Go from copy-pasting configs to designing your own agentic workflows with confidence. - ---- - - -## 📊 When to Use This Guide vs Everything-CC - -Both guides serve different needs. Choose based on your learning style: - -| Your Goal | Use This Guide | Use everything-claude-code | -|-----------|----------------|----------------------------| -| **Understand WHY** patterns work | ✅ Deep explanations + architecture | ❌ Config-focused | -| **Quick setup** for projects | ⚠️ Available but not primary focus | ✅ Battle-tested production configs | -| **Learn trade-offs** (agents vs skills) | ✅ Decision frameworks + comparisons | ❌ Lists patterns, no trade-off analysis | -| **Security hardening** | ✅ Only threat database (22 CVEs) | ⚠️ Basic patterns only | -| **Test understanding** | ✅ 257-question quiz | ❌ Not available | -| **Methodologies** (TDD/SDD/BDD) | ✅ Full workflow guides | ❌ Not covered | -| **Copy-paste ready** templates | ✅ 111 templates | ✅ 200+ templates | - -**Recommended workflow**: -1. **Learn concepts here** → Understand mental models, trade-offs, security -2. **Leverage production configs there** → Quick project setup from battle-tested patterns -3. **Return here for deep dives** → When you need to understand why something isn't working or design custom workflows - -**Both resources are complementary, not competitive.** Use what fits your current need. - ---- - -## ⚡ Quick Start - -**Quickest path**: [Cheat Sheet](./guide/cheatsheet.md) — 1 printable page with daily essentials - -**Interactive onboarding** (no clone needed): -```bash -claude "Fetch and follow the onboarding instructions from: https://raw.githubusercontent.com/FlorianBruniaux/claude-code-ultimate-guide/main/tools/onboarding-prompt.md" -``` - -**Browse directly**: [Full Guide](./guide/ultimate-guide.md) | [Examples](./examples/) | [Quiz](./quiz/) - -
-Prerequisites & Minimal CLAUDE.md Template - -**Prerequisites**: Node.js 18+ | [Anthropic API key](https://console.anthropic.com/) - -```markdown -# Project: [NAME] - -## Tech Stack -- Language: [e.g., TypeScript] -- Framework: [e.g., Next.js 14] -- Testing: [e.g., Vitest] - -## Commands -- Build: `npm run build` -- Test: `npm test` -- Lint: `npm run lint` - -## Rules -- Run tests before marking tasks complete -- Follow existing code patterns -- Keep commits atomic and conventional -``` - -Save as `CLAUDE.md` in your project root. Claude reads it automatically. - -
- ---- - -## 📁 Repository Structure - -```mermaid -graph LR - root[📦 Repository
Root] - - root --> guide[📖 guide/
19K lines] - root --> examples[📋 examples/
111 templates] - root --> quiz[🧠 quiz/
257 questions] - root --> tools[🔧 tools/
utils] - root --> machine[🤖 machine-readable/
AI index] - root --> docs[📚 docs/
56 evaluations] - - style root fill:#d35400,stroke:#e67e22,stroke-width:3px,color:#fff - style guide fill:#2980b9,stroke:#3498db,stroke-width:2px,color:#fff - style examples fill:#8e44ad,stroke:#9b59b6,stroke-width:2px,color:#fff - style quiz fill:#d68910,stroke:#f39c12,stroke-width:2px,color:#fff - style tools fill:#5d6d7e,stroke:#7f8c8d,stroke-width:2px,color:#fff - style machine fill:#138d75,stroke:#16a085,stroke-width:2px,color:#fff - style docs fill:#c0392b,stroke:#e74c3c,stroke-width:2px,color:#fff -``` - -
-Detailed Structure (Text View) - -``` -📦 claude-code-ultimate-guide/ -│ -├─ 📖 guide/ Core Documentation (~19K lines) -│ ├─ ultimate-guide.md Complete reference, 10 sections -│ ├─ cheatsheet.md 1-page printable -│ ├─ architecture.md How Claude Code works internally -│ ├─ methodologies.md TDD, SDD, BDD workflows -│ ├─ mcp-servers-ecosystem.md Official & community MCP servers -│ └─ workflows/ Step-by-step guides -│ -├─ 📋 examples/ 111 Production Templates -│ ├─ agents/ 6 custom AI personas -│ ├─ commands/ 22 slash commands -│ ├─ hooks/ 18 security hooks (bash + PowerShell) -│ ├─ skills/ 1 meta-skill (Claudeception) -│ └─ scripts/ Utility scripts (audit, search) -│ -├─ 🧠 quiz/ 257 Questions -│ ├─ 9 categories Setup, Agents, MCP, Trust, Advanced... -│ ├─ 4 profiles Junior, Senior, Power User, PM -│ └─ Instant feedback Doc links + score tracking -│ -├─ 🔧 tools/ Interactive Utilities -│ ├─ onboarding-prompt Personalized guided tour -│ └─ audit-prompt Setup audit & recommendations -│ -├─ 🤖 machine-readable/ AI-Optimized Index -│ ├─ reference.yaml Structured index (~2K tokens) -│ └─ llms.txt Standard LLM context file -│ -└─ 📚 docs/ 55 Resource Evaluations - └─ resource-evaluations/ 5-point scoring, source attribution -``` - -
- ---- - - -## 🎯 What Makes This Guide Unique - -### 🎓 Deep Understanding Over Configuration - -**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) -- [Trade-offs](./guide/ultimate-guide.md#when-to-use-what) — Decision frameworks for agents vs skills vs commands -- [Pitfalls](./guide/ultimate-guide.md#common-mistakes) — Common failure modes + prevention strategies - -**What this means for you**: Troubleshoot issues independently, optimize for your specific use case, know when to deviate from patterns. - ---- - -### 🛡️ Security Threat Intelligence (Only Comprehensive Database) - -**Outcome**: Protect production systems from AI-specific attacks. - -**Only guide with systematic threat tracking**: -- **22 CVE-mapped vulnerabilities** — Prompt injection, data exfiltration, code injection -- **341 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) - -**What this means for you**: Vet MCP servers before trusting them, detect attack patterns in configs, comply with security audits. - ---- - -### 📝 257-Question Knowledge Validation (Unique in Ecosystem) - -**Outcome**: Verify your understanding + identify knowledge gaps. - -**Only comprehensive assessment available** — test across 9 categories: -- Setup & Configuration, Agents & Sub-Agents, MCP Servers, Trust & Verification, Advanced Patterns - -**Features**: 4 skill profiles (Junior/Senior/Power User/PM), instant feedback with doc links, weak area identification - -[Try Quiz Online →](https://florianbruniaux.github.io/claude-code-ultimate-guide-landing/quiz/) | [Run Locally](./quiz/) - -**What this means for you**: Know what you don't know, track learning progress, prepare for team adoption discussions. - ---- - -### 🤖 Agent Teams Coverage (v2.1.32+ Experimental) - -**Outcome**: Parallelize work on large codebases (Fountain: 50% faster, CRED: 2x speed). - -**Only comprehensive guide to Anthropic's multi-agent coordination**: -- Production metrics from real companies (autonomous C compiler, 500K hours saved) -- 5 validated workflows (multi-layer review, parallel debugging, large-scale refactoring) -- Decision framework: Teams vs Multi-Instance vs Dual-Instance vs Beads - -[Agent Teams Workflow →](./guide/workflows/agent-teams.md) | [Section 9.20 →](./guide/ultimate-guide.md#920-agent-teams-multi-agent-coordination) - -**What this means for you**: Break monolithic tasks into parallelizable work, coordinate multi-file refactors, review your own AI-generated code. - ---- - -### 🔬 Methodologies (Structured Development Workflows) - -**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) - -**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. - ---- - -### 📚 111 Annotated Templates - -**Outcome**: Learn patterns, not just configs. - -Educational templates with explanations: -- Agents (6), Commands (22), Hooks (18), Skills -- Comments explaining **why** each pattern works (not just what it does) -- Gradual complexity progression (simple → advanced) - -[Browse Catalog →](./examples/) - -**What this means for you**: Understand the reasoning behind patterns, adapt templates to your context, create your own custom patterns. - ---- - -### 🔍 55 Resource Evaluations - -**Outcome**: Trust our recommendations are evidence-based. - -Systematic assessment of external resources (5-point scoring): -- Articles, videos, tools, frameworks -- Honest assessments with source attribution (no marketing fluff) -- Integration recommendations with trade-offs - -[See Evaluations →](./docs/resource-evaluations/) - -**What this means for you**: Save time vetting resources, understand limitations before adopting tools, make informed decisions. - ---- - -## 🎯 Learning Paths - -
-Junior Developer — Foundation path (7 steps) - -1. [Quick Start](./guide/ultimate-guide.md#1-quick-start-day-1) — Install & first workflow -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 ⭐ -6. [TDD Workflow](./guide/workflows/tdd-with-claude.md) — Test-first development -7. [Cheat Sheet](./guide/cheatsheet.md) — Print this - -
- -
-Senior Developer — Intermediate path (6 steps) - -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 -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 - -
- -
-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 -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 -7. [Agent Teams](./guide/workflows/agent-teams.md) — Multi-agent coordination (Opus 4.6 experimental) -8. [Examples](./examples/) — Production templates - -
- -
-Product Manager / DevOps / Designer - -**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 -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 - -**Product Designer** (5 steps): -1. [Working with Images](./guide/ultimate-guide.md#24-working-with-images) — Image analysis -2. [Wireframing Tools](./guide/ultimate-guide.md#wireframing-tools) — ASCII/Excalidraw -3. [Figma MCP](./guide/ultimate-guide.md#figma-mcp) — Design file access -4. [Design-to-Code Workflow](./guide/workflows/design-to-code.md) — Figma → Claude -5. [Cheat Sheet](./guide/cheatsheet.md) — Print this - -
- -### Progressive Journey - -- **Week 1**: Foundations (install, CLAUDE.md, first agent) -- **Week 2**: Core Features (skills, hooks, trust calibration) -- **Week 3**: Advanced (MCP servers, methodologies) -- **Month 2+**: Production mastery (CI/CD, observability) - ---- - -## 🔧 Rate Limits & Cost Savings - -**cc-copilot-bridge** routes Claude Code through GitHub Copilot Pro+ for flat-rate access ($10/month instead of per-token billing). - -```bash -# Install -git clone https://github.com/FlorianBruniaux/cc-copilot-bridge.git && cd cc-copilot-bridge && ./install.sh - -# Use -ccc # Copilot mode (flat $10/month) -ccd # Direct Anthropic mode (per-token) -cco # Offline mode (Ollama, 100% local) -``` - -**Benefits**: Multi-provider switching, rate limit bypass, 99%+ cost savings on heavy usage. - -→ **[cc-copilot-bridge](https://github.com/FlorianBruniaux/cc-copilot-bridge)** - ---- - -## 🔑 Golden Rules - -1. **Start small** — First project: 10-15 lines CLAUDE.md max -2. **Read before edit** — Always Read → Understand → Edit (never blind Write) -3. **Test-first** — Write test → Watch fail → Implement → Pass -4. **Use `/compact`** before context hits 70% — prevention beats recovery -5. **Review everything** — AI code has 1.75× more logic errors ([source](https://dl.acm.org/doi/10.1145/3716848)) -6. **Context = Gold** — Clear CLAUDE.md > clever prompts - -> Context management is critical. See the [Cheat Sheet](./guide/cheatsheet.md#context-management-critical) for thresholds and actions. - ---- - -## 🤖 For AI Assistants - -| Resource | Purpose | Tokens | -|----------|---------|--------| -| **[llms.txt](./machine-readable/llms.txt)** | Standard context file | ~1K | -| **[reference.yaml](./machine-readable/reference.yaml)** | Structured index with line numbers | ~2K | - -**Quick load**: `curl -sL https://raw.githubusercontent.com/FlorianBruniaux/claude-code-ultimate-guide/main/machine-readable/reference.yaml` - ---- - -## 🌍 Ecosystem - -### Claude Cowork (Non-Developers) - -**Claude Cowork** is the companion guide for non-technical users (knowledge workers, assistants, managers). - -Same agentic capabilities as Claude Code, but through a visual interface with no coding required. - -→ **[Claude Cowork Guide](https://github.com/FlorianBruniaux/claude-cowork-guide)** — File organization, document generation, automated workflows - -**Status**: Research preview (Pro $20/mo or Max $100-200/mo, macOS only, **VPN incompatible**) - -### Complementary Resources - -| Project | Focus | Best For | -|---------|-------|----------| -| [everything-claude-code](https://github.com/affaan-m/everything-claude-code) | Production configs (31.9k⭐) | Quick setup, battle-tested patterns | -| [claude-code-templates](https://github.com/davila7/claude-code-templates) | Distribution (200+ templates) | CLI installation (17k⭐) | -| [anthropics/skills](https://github.com/anthropics/skills) | Official Anthropic skills (60K+⭐) | Documents, design, dev templates | -| [anthropics/claude-plugins-official](https://skills.sh/anthropics/claude-plugins-official) | Plugin dev tools (3.1K installs) | CLAUDE.md audit, automation discovery | -| [skills.sh](https://skills.sh/) | Skills marketplace | One-command install (Vercel Labs) | -| [awesome-claude-code](https://github.com/hesreallyhim/awesome-claude-code) | Curation | Resource discovery | -| [awesome-claude-skills](https://github.com/BehiSecc/awesome-claude-skills) | Skills taxonomy | 62 skills across 12 categories | -| [awesome-claude-md](https://github.com/josix/awesome-claude-md) | CLAUDE.md examples (31★) | Annotated configs with scoring | -| [AI Coding Agents Matrix](https://coding-agents-matrix.dev) | Technical comparison | Comparing 23+ alternatives | - -**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 - ---- - -## 🛡️ Security - -**Comprehensive MCP security coverage** — the only guide with a threat intelligence database and production hardening workflows. - -### Official Security Tools - -| Tool | Purpose | Maintained By | -|------|---------|---------------| -| [claude-code-security-review](https://github.com/anthropics/claude-code-security-review) | GitHub Action for automated security scanning | Anthropic (official) | -| This Guide's Threat DB | Intelligence layer (22 CVEs, 341 malicious skills) | Community | - -**Workflow**: Use GitHub Action for automation → Consult Threat DB for threat intelligence. - -### Threat Database - -**22 CVE-mapped vulnerabilities** and **341 malicious skills** tracked in [`machine-readable/threat-db.yaml`](./machine-readable/threat-db.yaml): - -| Threat Category | Count | Examples | -|----------------|-------|----------| -| **Prompt Injection** | 14 CVEs | Indirect injection (CVE-2024-1546), context poisoning | -| **Data Exfiltration** | 5 CVEs | Training data extraction (CVE-2024-0241), secret leakage | -| **Code Injection** | 3 CVEs | Tool manipulation, workflow abuse | -| **Malicious Skills** | 341 patterns | Unicode injection, hidden instructions, auto-execute | - -**Taxonomies**: 10 attack surfaces × 11 threat types × 8 impact levels - -### Hardening Resources - -| 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 Commands - -```bash -/security-check # Quick scan config vs known threats (~30s) -/security-audit # Full 6-phase audit with score /100 (2-5min) -/update-threat-db # Research & update threat intelligence -/audit-agents-skills # Quality audit with security checks -``` - -### Security Hooks - -**18 production hooks** (bash + PowerShell) in [`examples/hooks/`](./examples/hooks/): - -| Hook | Purpose | -|------|---------| -| [dangerous-actions-blocker](./examples/hooks/bash/dangerous-actions-blocker.sh) | Block `rm -rf`, force-push, production ops | -| [prompt-injection-detector](./examples/hooks/bash/prompt-injection-detector.sh) | Detect injection patterns in CLAUDE.md/prompts | -| [unicode-injection-scanner](./examples/hooks/bash/unicode-injection-scanner.sh) | Detect hidden Unicode (zero-width, RTL override) | -| [output-secrets-scanner](./examples/hooks/bash/output-secrets-scanner.sh) | Prevent API keys/tokens in Claude responses | - -**[Browse All Security Hooks →](./examples/hooks/)** - -### MCP Vetting Workflow - -**Systematic evaluation before trusting MCP servers:** - -1. **Provenance**: GitHub verified, 100+ stars, active maintenance -2. **Code Review**: Minimal privileges, no obfuscation, open-source -3. **Permissions**: Whitelist-only filesystem access, network restrictions -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)** - ---- - -## 📖 About - -
-Origins & Philosophy - - -This guide is the result of **6 months of daily practice** with Claude Code. I don't claim expertise—I'm sharing what I've learned to help peers and evangelize AI-assisted development best practices. - -**Philosophy**: Learning journey over reference manual. Understanding **why** before **how**. Progressive complexity — start simple, master advanced at your pace. - -**Created with Claude Code**. Community-validated through contributions and feedback. - -**Key Inspirations**: -- [Claudelog.com](https://claudelog.com/) — Excellent patterns & tutorials -- [zebbern/claude-code-guide](https://github.com/zebbern/claude-code-guide) — Comprehensive reference with security focus -- [ykdojo/claude-code-tips](https://github.com/ykdojo/claude-code-tips) — Practical productivity techniques - -
- -
-Privacy & Data - -Claude Code sends your prompts, file contents, and MCP results to Anthropic servers. -- **Default**: 5 years retention (training enabled) | **Opt-out**: 30 days | **Enterprise**: 0 -- **Action**: [Disable training](https://claude.ai/settings/data-privacy-controls) | [Full privacy guide](./guide/data-privacy.md) - -
- ---- - -## 📚 What's Inside - -### Core Documentation - -| File | Purpose | Time | -|------|---------|------| -| **[Ultimate Guide](./guide/ultimate-guide.md)** | Complete reference (~19K 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 | -| **[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 | - -
-Examples Library (111 templates) - -**Agents** (6): [code-reviewer](./examples/agents/code-reviewer.md), [test-writer](./examples/agents/test-writer.md), [security-auditor](./examples/agents/security-auditor.md), [refactoring-specialist](./examples/agents/refactoring-specialist.md), [output-evaluator](./examples/agents/output-evaluator.md), [devops-sre](./examples/agents/devops-sre.md) ⭐ - -**Slash Commands** (22): [/pr](./examples/commands/pr.md), [/commit](./examples/commands/commit.md), [/release-notes](./examples/commands/release-notes.md), [/diagnose](./examples/commands/diagnose.md), [/security](./examples/commands/security.md), [/security-check](./examples/commands/security-check.md) **, [/security-audit](./examples/commands/security-audit.md) **, [/update-threat-db](./examples/commands/update-threat-db.md) **, [/refactor](./examples/commands/refactor.md), [/explain](./examples/commands/explain.md), [/optimize](./examples/commands/optimize.md), [/ship](./examples/commands/ship.md)... - -**Security Hooks** (18): [dangerous-actions-blocker](./examples/hooks/bash/dangerous-actions-blocker.sh), [prompt-injection-detector](./examples/hooks/bash/prompt-injection-detector.sh), [unicode-injection-scanner](./examples/hooks/bash/unicode-injection-scanner.sh), [output-secrets-scanner](./examples/hooks/bash/output-secrets-scanner.sh)... - -**Skills** (1): [Claudeception](https://github.com/blader/Claudeception) — Meta-skill that auto-generates skills from session discoveries ⭐ - -**Plugins** (1): [SE-CoVe](./examples/plugins/se-cove.md) — Chain-of-Verification for independent code review (Meta AI, ACL 2024) - -**Utility Scripts**: [session-search.sh](./examples/scripts/session-search.sh), [audit-scan.sh](./examples/scripts/audit-scan.sh) - -**GitHub Actions**: [claude-pr-auto-review.yml](./examples/github-actions/claude-pr-auto-review.yml), [claude-security-review.yml](./examples/github-actions/claude-security-review.yml), [claude-issue-triage.yml](./examples/github-actions/claude-issue-triage.yml) - -**Integrations** (1): [Agent Vibes TTS](./examples/integrations/agent-vibes/) - Text-to-speech narration for Claude Code responses - -**[Browse Complete Catalog](./examples/README.md)** | **[Interactive Catalog](./examples/index.html)** - -
- -
-Knowledge Quiz (257 questions) - -Test your Claude Code knowledge with an interactive CLI quiz covering all guide sections. - -```bash -cd quiz && npm install && npm start -``` - -**Features**: 4 profiles (Junior/Senior/Power User/PM), 10 topic categories, immediate feedback with doc links, score tracking with weak area identification. - -**[Quiz Documentation](./quiz/README.md)** | **[Contribute Questions](./quiz/templates/question-template.yaml)** - -
- -
-Resource Evaluations (55 assessments) - -Systematic evaluation of external resources (tools, methodologies, articles) before integration into the guide. - -**Methodology**: 5-point scoring system (Critical → Low) with technical review and challenge phase for objectivity. - -**Evaluations**: GSD methodology, Worktrunk, Boris Cowork video, AST-grep, ClawdBot analysis, and more. - -**[Browse Evaluations](./docs/resource-evaluations/)** | **[Evaluation Methodology](./docs/resource-evaluations/README.md)** - -
- ---- - -## 🤝 Contributing - -We welcome: -- ✅ Corrections and clarifications -- ✅ New quiz questions -- ✅ Methodologies and workflows -- ✅ Resource evaluations (see [process](./docs/resource-evaluations/README.md)) -- ✅ Educational content improvements - -See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines. - -**Ways to Help**: Star the repo • Report issues • Submit PRs • Share workflows in [Discussions](../../discussions) - ---- - -## 📄 License & Support - -**Guide**: [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) — Educational content is open for reuse with attribution. - -**Templates**: [CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/) — Copy-paste freely, no attribution needed. - -**Author**: [Florian BRUNIAUX](https://github.com/FlorianBruniaux) | Founding Engineer [@Méthode Aristote](https://methode-aristote.fr) - -**Stay Updated**: [Watch releases](../../releases) | [Discussions](../../discussions) | [Connect on LinkedIn](https://www.linkedin.com/in/florian-bruniaux-43408b83/) - ---- - -## 📚 Further Reading - -### 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 - -### Official Resources -- [Claude Code CLI](https://code.claude.com) — Official website -- [Documentation](https://code.claude.com/docs) — Official docs -- [Anthropic CHANGELOG](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md) — Official Claude Code changelog -- [GitHub Issues](https://github.com/anthropics/claude-code/issues) — Bug reports & feature requests - -### Research & Industry Reports - -- **[2026 Agentic Coding Trends Report](https://resources.anthropic.com/hubfs/2026%20Agentic%20Coding%20Trends%20Report.pdf)** (Anthropic, Feb 2026) - - 8 trends prospectifs (foundation/capability/impact) - - Case studies: Fountain (50% faster), Rakuten (7h autonomous), CRED (2x speed), TELUS (500K hours saved) - - Research data: 60% AI usage, 0-20% full delegation, 67% more PRs merged/day - - **Evaluation**: [`docs/resource-evaluations/anthropic-2026-agentic-coding-trends.md`](docs/resource-evaluations/anthropic-2026-agentic-coding-trends.md) (score 4/5) - - **Integration**: Diffused across sections 9.17 (Multi-Instance ROI), 9.20 (Agent Teams adoption), 9.11 (Enterprise Anti-Patterns), Section 9 intro - -### Community Resources -- [everything-claude-code](https://github.com/affaan-m/everything-claude-code) — Production configs (31.9k⭐) -- [awesome-claude-code](https://github.com/hesreallyhim/awesome-claude-code) — Curated links -- [SuperClaude Framework](https://github.com/SuperClaude-Org/SuperClaude_Framework) — Behavioral modes - -### Tools -- [Ask Zread](https://zread.ai/FlorianBruniaux/claude-code-ultimate-guide) — Ask questions about this guide -- [Interactive Quiz](./quiz/) — 257 questions -- [Landing Site](https://florianbruniaux.github.io/claude-code-ultimate-guide-landing/) — Visual navigation - ---- - -*Version 3.26.0 | Updated daily · Feb 12, 2026 | Crafted with Claude* - - - diff --git a/docs/drafts/reddit-post.md b/docs/drafts/reddit-post.md deleted file mode 100644 index 42f9b4a..0000000 --- a/docs/drafts/reddit-post.md +++ /dev/null @@ -1,195 +0,0 @@ -# Reddit Post Draft — Differentiation Strategy - -**Target**: r/ClaudeAI (primary) -**Posting Window**: Tuesday–Thursday, 9–11am EST -**Strategy**: Lead with WHY (educational depth), security-first (threat DB), complementary positioning - ---- - -## Title (Recommended) - -**Claude Code's docs don't teach you WHY. Here's the educational guide with threat intelligence (22 CVEs), 257-question quiz, and 18 production security hooks.** - -### Alternative Titles - -**Option B** (experience-driven): -> I spent 6 months with Claude Code daily. Here's the guide I wish existed: threat intelligence, methodologies, and production templates. - -**Option C** (problem-solution): -> Claude Code's docs show you WHAT to do. This guide shows you WHY it works and WHEN it breaks. - ---- - -## Post Body - -```markdown -**The gap**: Claude Code's official docs are solid references. But they don't explain WHY patterns work, don't address security threats systematically, and don't provide structured learning paths from junior to power user. - -**What I built** (6 months daily practice, zero marketing BS): - -**Security-First** (unique in the ecosystem): -- 🛡️ Threat intelligence database: 22 CVEs, 341 malicious skills tracked -- 🔒 18 production security hooks (bash + PowerShell) — drop-in, no config -- ⚠️ MCP vetting workflow: how to audit third-party servers before they access your codebase - -**Educational Depth** (not just configs): -- 📖 19K-line guide: explains concepts first, not just configs -- 🧠 257-question quiz (only comprehensive Claude Code assessment available) -- 📊 4 learning paths: Junior → Senior → Power User → PM/DevOps/Designer -- 🔬 TDD/SDD/BDD/GSD methodologies documented with real workflows - -**Production Templates** (111 total, CC0 licensed): -- Agents: Technical Writer, Security Auditor, Code Reviewer (with behavioral mindsets) -- Commands: `/commit`, `/refactor`, `/security-audit`, `/release` -- Hooks: Pre-commit, post-merge, security scanning -- Skills: Git workflows, testing patterns, deployment automation - -**Quality Assurance**: -- 55 external resource evaluations (5-point scoring system) -- Only guide with systematic competitive analysis -- Architecture doc: how Claude Code works under the hood - -**Positioning** (important): -- **Complementary** to everything-claude-code (learn WHY here → leverage battle-tested configs there) -- **Educational** vs tooling (if you want multi-agent orchestration, check ruvnet/claude-flow) -- **Security-focused** vs generic tips - -**Quick start** (no clone needed): -```bash -claude "Fetch https://raw.githubusercontent.com/FlorianBruniaux/claude-code-ultimate-guide/main/tools/onboarding-prompt.md" -``` - -Or dive in: -- [Cheatsheet (1 page)](https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/cheatsheet.md) — printable quick ref -- [Quiz](https://github.com/FlorianBruniaux/claude-code-ultimate-guide/tree/main/quiz) — test your knowledge (4 profiles) -- [Threat DB](https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/machine-readable/threat-db.yaml) — 22 CVEs, 341 malicious skills -- [Full Guide](https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md) — 19K lines, concepts-first - -**Licensing**: -- Guide: CC BY-SA 4.0 (attribution required) -- Templates: CC0 (copy-paste, zero attribution) - -**Repo**: https://github.com/FlorianBruniaux/claude-code-ultimate-guide - -If this helps your workflow, a ⭐ helps others discover it. - ---- - -**Why I built this**: I kept hitting security issues and pattern failures that the docs didn't explain. Spent 6 months documenting WHY patterns work, WHEN they break, and HOW to recover. This is the resource I wish existed when I started. -``` - ---- - -## Post-Posting Strategy - -### Critical Engagement Window (T+0 to T+3h) - -**T+0 to T+1h** (highest priority): -- Reply to ALL comments within 15 minutes -- Use prepared responses from `claudedocs/reddit-responses-prepared.md` -- Tone: Bold Guy (direct, bienveillant, énergique) — not defensive - -**T+1h to T+3h**: -- Active monitoring, 30-minute response cadence -- Identify emerging themes in comments -- Cross-link to specific guide sections (provide value in replies) - -**T+3h to T+24h**: -- Passive monitoring, 1-hour response cadence -- Track metrics: upvotes, comments, stars gained - -### Anticipated Critiques & Responses - -| Critique | Response Template | -|----------|------------------| -| "Just use everything-claude-code" | "Exactly! Learn concepts here → apply their battle-tested configs. Complementary, not competitive." | -| "Too long, overwhelming" | "That's why we have the 1-page cheatsheet + quiz paths. Start there, expand when you need depth." | -| "Security is overkill" | "22 CVEs disagree. If you're running untrusted MCP servers or community skills, the threat DB is essential." | -| "Why not contribute to official docs?" | "Different goals. Official docs = reference. This = educational + threat intelligence + methodologies." | -| "Stars = marketing spam" | "Fair concern. Verifiable: 257 quiz questions, 22 CVEs tracked, 55 resource evals. Check the work." | - -### Success Metrics (24h window) - -| Metric | Target | Tool | -|--------|--------|------| -| Reddit upvotes | >50 | Reddit analytics | -| Comments | >20 | Reddit analytics | -| Stars gained | >20 | GitHub Insights | -| Traffic spike | >500 unique | GitHub Insights | -| Discussions created | >5 | GitHub Discussions | - -**Success threshold**: 50+ upvotes, 20+ comments, 20+ stars in 24h. - ---- - -## Pre-Flight Checklist - -- [ ] Version badge accurate in README (currently 3.26.0) -- [ ] Templates count verified (111) -- [ ] Quiz questions count verified (257) -- [ ] Threat DB stats verified (22 CVEs, 341 malicious skills) -- [ ] Landing site synchronized (`./scripts/check-landing-sync.sh`) -- [ ] All links tested: - - [ ] Onboarding prompt - - [ ] Cheatsheet - - [ ] Quiz - - [ ] Threat DB - - [ ] Full guide -- [ ] No typos in post body -- [ ] Prepared responses ready (`claudedocs/reddit-responses-prepared.md`) - ---- - -## Red Flags to Avoid - -| ❌ Never Say | ✅ Say Instead | -|--------------|----------------| -| "Best guide" | "Most comprehensive I've found" | -| "everything-claude-code is outdated" | "Complementary to everything-claude-code" | -| "Trust me" | "Verifiable via [specific link]" | -| "Sorry if..." | (No unnecessary apologies) | -| Aggressive self-promo | Factual claims with sources | -| "Blazingly fast" | Specific metrics (e.g., "22 CVEs tracked") | - ---- - -## Differentiation Highlights (for replies) - -When responding to comments, emphasize these unique angles: - -**Security-First**: -- Only guide with threat intelligence database (22 CVEs, 341 malicious skills) -- Only guide with production security hooks (18 total, bash + PowerShell) -- MCP vetting workflow documented (how to audit before trusting) - -**Educational Depth**: -- Explains WHY patterns work, not just configs -- 257-question quiz (only comprehensive assessment) -- 4 learning paths (skill-based progression) - -**Methodologies**: -- TDD/SDD/BDD/GSD workflows documented -- Not just tools — systematic approaches to different project types - -**Complementary Positioning**: -- Learn concepts → Apply everything-claude-code configs -- Educational layer vs production configs -- No competition with ecosystem leaders - ---- - -## Timeline - -| Time | Action | Owner | -|------|--------|-------| -| Pre-post | Verify checklist above | Florian | -| Post day, 9-11am EST | Publish post | Florian | -| T+0 to T+1h | Reply to ALL comments (<15min) | Florian | -| T+1h to T+3h | Active monitoring (30min cadence) | Florian | -| T+3h to T+24h | Passive monitoring (1h cadence) | Florian | -| T+24h | Analyze metrics, assess success | Florian | -| T+7d | Post-mortem, document learnings | Florian | - ---- - -**Status**: ✅ Ready for review (pending checklist verification) diff --git a/docs/drafts/resource-comparison.md b/docs/drafts/resource-comparison.md deleted file mode 100644 index e805151..0000000 --- a/docs/drafts/resource-comparison.md +++ /dev/null @@ -1,244 +0,0 @@ -# Claude Code Resources: Comparison Matrix - -## When to Use What - -This comparison helps you choose the right resource based on your needs, experience level, and learning style. - -### Resource Overview - -| Resource | Primary Focus | Maintained By | Last Update | -|----------|---------------|---------------|-------------| -| [Official Anthropic Docs](https://docs.anthropic.com/en/docs/agents-and-agentic-systems/claude-code) | Reference & API | Anthropic | Active | -| [everything-claude-code](https://github.com/everythinggptresources/everything-claude-code) | Configs & Operations | Community | Active | -| **This Guide** (Ultimate Guide) | Education & WHY | Independent | Active | -| [claude-flow](https://github.com/meistrari/claude-flow) | Tooling & Orchestration | Community | Active | - ---- - -## Quick Decision Tree - -``` -Need official API reference? → Anthropic Docs -Want copy-paste configs? → everything-claude-code -Want to understand WHY? → This Guide (Ultimate Guide) -Need workflow automation? → claude-flow -``` - ---- - -## Detailed Comparison Matrix - -### 1. Audience Profile - -| Resource | Beginner | Intermediate | Advanced | Expert | -|----------|----------|--------------|----------|--------| -| **Anthropic Docs** | ⚠️ Assumes knowledge | ✅ Good fit | ✅ Primary source | ✅ API reference | -| **everything-claude-code** | ✅ Quick wins | ✅ Practical examples | ⚠️ Limited depth | ❌ Too basic | -| **This Guide** | ✅ Start here | ✅ Core audience | ✅ Deep dives available | ⚠️ May be verbose | -| **claude-flow** | ❌ Requires CLI expertise | ⚠️ Learning curve | ✅ Productivity boost | ✅ Power users | - -**Legend**: ✅ Excellent fit | ⚠️ Partial fit | ❌ Poor fit - ---- - -### 2. Use Case Mapping - -| Use Case | Best Resource | Alternative | Why | -|----------|---------------|-------------|-----| -| **API integration** | Anthropic Docs | - | Official specifications, SDK examples | -| **First-time setup** | This Guide | everything-claude-code | Explains trade-offs, not just steps | -| **Ready-to-use configs** | everything-claude-code | This Guide (examples/) | Pre-built agents, hooks, skills | -| **Understanding architecture** | This Guide | Anthropic Docs | Explains HOW it works internally | -| **Debugging workflows** | This Guide | claude-flow | Methodology-driven troubleshooting | -| **Team workflows** | claude-flow | This Guide (workflows/) | Git integration, multi-user patterns | -| **Learning WHY** | This Guide | - | Only resource with educational depth | -| **Quick reference** | This Guide (cheatsheet) | Anthropic Docs | 1-page printable | -| **Testing knowledge** | This Guide (quiz) | - | Only resource with assessment | -| **Automation/scripting** | claude-flow | everything-claude-code | Orchestration layer, CLI wrappers | - ---- - -### 3. Content Type & Depth - -| Dimension | Anthropic Docs | everything-claude-code | This Guide | claude-flow | -|-----------|----------------|------------------------|------------|-------------| -| **Reference Material** | ⭐⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐ | -| **Templates/Examples** | ⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | -| **Educational Content** | ⭐⭐ | ⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐ | -| **Tooling/Automation** | ⭐ | ⭐⭐ | ⭐⭐ | ⭐⭐⭐⭐⭐ | -| **Troubleshooting** | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | -| **Conceptual Depth** | ⭐⭐⭐ | ⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐ | -| **Code Quality** | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | - -**Rating Scale**: ⭐ Minimal → ⭐⭐⭐⭐⭐ Best-in-class - ---- - -### 4. Learning Approach Compatibility - -| Learning Style | Recommended Resource | Why | -|----------------|---------------------|-----| -| **Copy-Paste (Quick Wins)** | everything-claude-code | 100+ configs ready to use | -| **Understand-First** | This Guide | Explains architecture, trade-offs, pitfalls | -| **Experiment-Driven** | claude-flow | Test workflows in isolated sandboxes | -| **API-Driven** | Anthropic Docs | Official specifications, SDK integration | -| **Visual Learner** | This Guide | Mermaid diagrams, architecture visuals | -| **Assessment-Based** | This Guide (quiz) | 257 questions with instant feedback | -| **Problem-Solver** | This Guide (troubleshooting) | Systematic debugging methodologies | - ---- - -### 5. Content Depth Comparison - -| Topic | Anthropic Docs | everything-claude-code | This Guide | claude-flow | -|-------|----------------|------------------------|------------|-------------| -| **CLAUDE.md Structure** | Surface | Examples | Deep (architecture, best practices) | Minimal | -| **Custom Agents** | Surface | Templates only | Deep (design patterns, anti-patterns) | Orchestration | -| **MCP Servers** | Reference | List | Deep (when/why/how, 30+ servers) | Integration | -| **Security** | Basic | Moderate | Deep (22 CVEs, 341 malicious skills) | Minimal | -| **Testing Claude Code** | Minimal | None | Deep (TDD, SDD, BDD workflows) | Automation | -| **Trust Verification** | Basic | None | Deep (methodology, /insights analysis) | Minimal | -| **Hooks & Events** | Reference | 18 examples | Deep (security patterns, PowerShell) | Automation | -| **Performance** | Basic | None | Moderate (token efficiency) | Optimization | -| **Team Workflows** | None | Basic | Moderate | Advanced (Git integration) | - ---- - -### 6. Documentation Style - -| Aspect | Anthropic Docs | everything-claude-code | This Guide | claude-flow | -|--------|----------------|------------------------|------------|-------------| -| **Tone** | Technical, formal | Casual, example-driven | Educational, methodical | Developer-focused | -| **Structure** | API reference | Curated list | Book-like chapters | Tool documentation | -| **Examples** | Minimal, official | Abundant, varied | Contextualized, annotated | Integration-focused | -| **Maintenance** | Official cadence | Community-driven | Active (Feb 2026) | Periodic updates | -| **Versioning** | Tied to API | Unversioned | Semantic (v3.26.0) | Git tags | - ---- - -### 7. Unique Value Propositions - -| Resource | Unique Strengths | Cannot Find Elsewhere | -|----------|------------------|----------------------| -| **Anthropic Docs** | • Official API specs
• Guaranteed accuracy
• SDK integration examples | Official changelog, API contracts | -| **everything-claude-code** | • Largest config collection (100+)
• Community contributions
• Ready-to-use templates | Breadth of pre-built configurations | -| **This Guide** | • Educational depth (WHY/HOW)
• 257-question quiz
• Security threat database (22 CVEs, 341 malicious skills)
• Methodology guides (TDD/SDD/BDD)
• Architecture explanations | Conceptual understanding, assessment tools, security intelligence | -| **claude-flow** | • CLI orchestration
• Workflow automation
• Git integration patterns | Team collaboration workflows, automation tooling | - ---- - -### 8. Update Frequency & Maintenance - -| Resource | Update Cadence | Last Significant Update | Maintenance Model | -|----------|----------------|------------------------|-------------------| -| **Anthropic Docs** | Per API release | Ongoing (2026-02) | Official Anthropic team | -| **everything-claude-code** | Community-driven | 2026-01 | Crowdsourced contributions | -| **This Guide** | Weekly releases | 2026-02-12 (v3.26.0) | Single maintainer + agent team | -| **claude-flow** | Periodic | 2026-01 | Active maintainer | - ---- - -### 9. Complementary Usage Patterns - -#### Pattern 1: First-Time User Journey -``` -1. This Guide (architecture.md) → Understand how Claude Code works -2. Anthropic Docs → Verify API setup -3. everything-claude-code → Copy starter configs -4. This Guide (quiz) → Test understanding -``` - -#### Pattern 2: Production Deployment -``` -1. This Guide (security-hardening.md) → Security audit -2. claude-flow → Automate workflows -3. This Guide (examples/) → Hook templates -4. Anthropic Docs → API integration -``` - -#### Pattern 3: Power User Optimization -``` -1. This Guide (ultimate-guide.md) → Deep concepts -2. claude-flow → Workflow orchestration -3. Anthropic Docs → Advanced API features -4. This Guide (methodologies.md) → TDD/SDD patterns -``` - ---- - -### 10. Coverage Gaps & Overlaps - -| Topic | Anthropic Docs | everything-claude-code | This Guide | claude-flow | -|-------|----------------|------------------------|------------|-------------| -| **API Reference** | ✅ Complete | ❌ None | ⚠️ Practical subset | ❌ None | -| **Agent Design** | ⚠️ Surface | ✅ Templates | ✅ Deep patterns | ⚠️ Orchestration | -| **Security** | ⚠️ Basic | ⚠️ Examples | ✅ Threat DB + CVEs | ❌ None | -| **Quiz/Assessment** | ❌ None | ❌ None | ✅ 257 questions | ❌ None | -| **Workflow Automation** | ❌ None | ⚠️ Basic | ⚠️ Guides | ✅ Tooling | -| **Troubleshooting** | ⚠️ FAQ | ⚠️ Issues | ✅ Methodology | ⚠️ Logs | -| **Team Collaboration** | ❌ None | ❌ None | ⚠️ Patterns | ✅ Git integration | - -**Legend**: ✅ Comprehensive | ⚠️ Partial | ❌ Not covered - ---- - -## Recommendation Matrix - -### By Experience Level - -| You are... | Start with | Then explore | Power-up with | -|------------|------------|--------------|---------------| -| **Complete beginner** | This Guide (onboarding) | Anthropic Docs (setup) | everything-claude-code (templates) | -| **Junior developer** | This Guide (ultimate-guide.md) | This Guide (quiz) | Anthropic Docs (API) | -| **Mid-level engineer** | This Guide (workflows/) | claude-flow | Anthropic Docs (advanced) | -| **Senior/Lead** | This Guide (security-hardening) | claude-flow | Anthropic Docs (SDK) | -| **Team lead/Manager** | This Guide (methodologies) | claude-flow | This Guide (examples/agents/) | - -### By Primary Goal - -| Your goal | Primary Resource | Supporting Resources | -|-----------|------------------|---------------------| -| **Learn Claude Code** | This Guide (all sections) | Anthropic Docs (reference) | -| **Set up quickly** | everything-claude-code | This Guide (cheatsheet) | -| **Build production systems** | This Guide (security + examples) | claude-flow + Anthropic Docs | -| **Understand architecture** | This Guide (architecture.md) | Anthropic Docs (concepts) | -| **Automate workflows** | claude-flow | This Guide (examples/hooks/) | -| **Pass certification** | This Guide (quiz) | Anthropic Docs (API) | -| **Debug issues** | This Guide (troubleshooting) | Anthropic Docs (changelog) | - ---- - -## Summary Table: At a Glance - -| Criterion | Anthropic Docs | everything-claude-code | This Guide | claude-flow | -|-----------|----------------|------------------------|------------|-------------| -| **Best For** | API integration | Quick configs | Learning WHY | Automation | -| **Depth** | Reference | Examples | Deep | Tooling | -| **Audience** | All levels | Beginners/Intermediate | All levels | Advanced | -| **Update Frequency** | Official releases | Community | Weekly | Periodic | -| **Unique Value** | Official truth | Config breadth | Education + Quiz + Security | Orchestration | -| **Templates** | Minimal | 100+ | 111 | Integration-focused | -| **Learning Curve** | Moderate | Low | Low → High | High | -| **Maintenance** | Anthropic | Community | Single maintainer | Active dev | - ---- - -## Key Takeaway - -**Use all four resources together:** -- **Anthropic Docs** = Official reference when in doubt -- **everything-claude-code** = Quick-start templates -- **This Guide** = Deep understanding + security + assessment -- **claude-flow** = Production automation - -**This Guide's unique position**: Only resource that explains **WHY** and **HOW** with: -- Educational methodology (TDD/SDD/BDD) -- Security threat intelligence (22 CVEs, 341 malicious skills) -- Comprehensive assessment (257-question quiz) -- Architecture deep-dives (how Claude Code works internally) - -**No single resource covers everything** — combine them based on your current need. - ---- - -**Last Updated**: 2026-02-12 | Part of [Claude Code Ultimate Guide](https://github.com/FlorianBruniaux/claude-code-ultimate-guide) v3.26.0 diff --git a/guide/ai-roles.md b/guide/ai-roles.md new file mode 100644 index 0000000..57bf025 --- /dev/null +++ b/guide/ai-roles.md @@ -0,0 +1,552 @@ +--- +title: "AI Roles & Career Paths: The New Engineering Landscape" +description: "Comprehensive map of emerging AI roles — from Prompt Engineer to Harness Engineer — with responsibilities, required skills, and career trajectories" +tags: [roles, careers, ai-engineer, prompt-engineer, harness-engineer, context-engineer, guide] +--- + +# AI Roles & Career Paths: The New Engineering Landscape + +> **Last updated**: March 2026 +> +> **Confidence**: Tier 2 — Based on job market data, industry publications, and emerging field research +> +> **Reading time**: ~20 minutes + +The AI wave didn't just create new tools. It created new jobs that didn't exist 3 years ago and is reshaping what existing roles mean. This guide maps the full landscape: what each role does, what skills it requires, how they relate to each other, and where each one is heading. + +--- + +## Table of Contents + +1. [The Landscape in One View](#1-the-landscape-in-one-view) +2. [Prompt Engineer](#2-prompt-engineer) +3. [Context Engineer](#3-context-engineer) +4. [AI Engineer](#4-ai-engineer) +5. [LLM Engineer](#5-llm-engineer) +6. [AI Agent Engineer](#6-ai-agent-engineer) +7. [Founding AI Engineer](#7-founding-ai-engineer) +8. [AI Architect](#8-ai-architect) +9. [Platform Engineer (AI context)](#9-platform-engineer-ai-context) +10. [Harness Engineer](#10-harness-engineer) +11. [AI Product Manager](#11-ai-product-manager) +12. [AI Safety & Eval Engineer](#12-ai-safety--eval-engineer) +13. [ML Engineer](#13-ml-engineer) +14. [Career Decision Matrix](#14-career-decision-matrix) +15. [Salary Benchmarks (2025-2026)](#15-salary-benchmarks-2025-2026) +16. [What's Not a Role (Yet)](#16-whats-not-a-role-yet) +17. [Job Listings](#17-job-listings) + +--- + +## 1. The Landscape in One View + +Two axes structure this landscape: **proximity to the model** (are you training it, prompting it, or building infrastructure around it?) and **proximity to production** (research vs. shipped product). + +``` + ← Closer to the model Closer to infrastructure → + +Research ML Engineer ←────────────────────────── AI Architect + AI Safety Engineer Platform Engineer + │ │ + │ │ +Production LLM Engineer ──── AI Engineer ──── AI Agent Engineer + Context Engineer Harness Engineer + Prompt Engineer Founding AI Engineer + AI Product Manager +``` + +Most new job demand sits in the **bottom-right**: building reliable AI systems that ship and stay reliable in production. The "pure research" quadrant remains competitive and specialized. The highest growth is in the applied, product-facing roles. + +--- + +## 2. Prompt Engineer + +**Status**: First wave (2022-2023), partially commoditized but still relevant in specialized contexts. + +### What they do + +Craft and optimize the instructions sent to AI models to get reliable, high-quality outputs. The scope ranges from one-shot prompts to complex multi-step prompt chains for production systems. + +### Responsibilities + +- Design prompt templates for specific use cases (customer support, code generation, document analysis) +- Run systematic A/B tests to measure prompt performance +- Document prompt libraries and version them +- Optimize prompts for cost (fewer tokens, same quality) +- Work with domain experts to encode knowledge into prompts + +### Required skills + +| Technical | Soft | +|-----------|------| +| Understanding of LLM behavior and failure modes | Communication with non-technical stakeholders | +| Basic Python (for automation and testing) | Systematic experimentation mindset | +| Familiarity with evaluation frameworks | Attention to edge cases | +| Versioning practices | Documentation discipline | + +### Where it's heading + +The "prompt engineer" title as a standalone role is consolidating into broader AI Engineer or Context Engineer roles. Where it persists: companies with very specific, high-stakes prompt domains (legal, medical, financial compliance). Upskill toward context engineering or AI engineering if you're in this role. + +### Entry paths + +Technical writer, QA engineer, domain expert (law, medicine, finance), content strategist. + +--- + +## 3. Context Engineer + +**Status**: Emerging — one of the fastest-growing specializations in 2025. + +### What they do + +Context engineering is the evolution of prompt engineering. Where prompt engineers craft instructions, context engineers design **systems** that give AI models the right information, at the right time, in the right format. Andrej Karpathy explicitly moved from "vibe coding" framing to "context engineering" as the more precise description of this work. + +> "Context Engineering is providing the right information and tools, in the right format, at the right time." — Philipp Schmid, Google + +### Responsibilities + +- Design RAG (Retrieval-Augmented Generation) systems and knowledge bases +- Manage context windows across multi-turn interactions and long-horizon tasks +- Define what agents remember, retrieve, or forget during task execution +- Structure information hierarchies (system prompts, conversation history, retrieved docs, tool definitions, safety constraints) +- Optimize context for accuracy and cost simultaneously +- Measure context quality through systematic evals + +### Required skills + +| Technical | Soft | +|-----------|------| +| Python (context pipeline automation) | Systems thinking | +| Vector databases (Pinecone, Chroma, Weaviate) | Information architecture instinct | +| SQL and NoSQL (context retrieval) | Cross-functional collaboration | +| Cloud platforms (AWS/Azure/GCP) | Curiosity and continuous learning | +| RAG architectures, embedding models | Precision in documentation | + +### Relationship to other roles + +Context engineers work upstream of AI engineers (they define what context is available) and downstream of domain experts (they encode domain knowledge into retrievable structures). Closely related to platform engineers in large organizations. + +### Entry paths + +Data engineer, backend engineer, ML engineer, information architect. + +--- + +## 4. AI Engineer + +**Status**: Mainstream — the generalist role for building AI-powered products. + +### What they do + +Build end-to-end AI systems. Not researchers (they don't train models from scratch), but not just integrators either. They take LLMs and orchestration frameworks and build systems that ship. Think of them as software engineers who've added LLM integration, evals, and AI product intuition to their stack. + +### Responsibilities + +- Design and implement LLM-powered applications (chatbots, agents, pipelines) +- Build evaluation frameworks to measure model output quality +- Integrate AI capabilities into existing software systems +- Monitor AI systems in production (latency, cost, quality drift) +- Select appropriate models for specific tasks (capability vs. cost tradeoffs) +- Implement fine-tuning or RAG when base models aren't sufficient + +### Required skills + +| Technical | Soft | +|-----------|------| +| Strong software engineering foundations | Product judgment | +| Python (primary), JavaScript (often needed) | Pragmatism over research purity | +| Familiarity with major LLM APIs (Anthropic, OpenAI, Gemini) | Fast iteration mindset | +| Eval design and measurement | Ability to work with ambiguous requirements | +| Understanding of embeddings, RAG, agent frameworks | Communication of AI limitations to stakeholders | +| MLOps basics (deployment, monitoring, versioning) | | + +### The critical distinction from ML Engineer + +AI engineers work with existing models. ML engineers build and train models. In practice, most companies hiring in 2025-2026 need AI engineers (apply the models) not ML engineers (build the models). + +### Entry paths + +Software engineer (most common), backend engineer, data engineer, ML engineer transitioning to applied work. + +--- + +## 5. LLM Engineer + +**Status**: Specialized variant of AI Engineer, prominent in model-heavy companies. + +### What they do + +Deep specialization in large language model integration and optimization. Where AI engineers are generalists, LLM engineers go deep on the model layer: fine-tuning, RLHF, model selection, prompt optimization at scale, and evaluation infrastructure. + +### Responsibilities + +- Fine-tuning base models for domain-specific tasks +- Designing and running systematic model evaluations (evals) +- Implementing RLHF or similar feedback mechanisms +- Model performance benchmarking and regression testing +- Managing model versions and A/B testing new model releases +- Building tooling for model monitoring and drift detection + +### Required skills + +| Technical | Soft | +|-----------|------| +| Python (fluent) | Scientific rigor | +| PyTorch or JAX | Statistical thinking | +| Transformers architecture knowledge | Patience with slow feedback loops | +| Evaluation framework design | Documentation of experiments | +| Distributed training basics | | + +### Where it's heading + +Strong demand at AI companies (Anthropic, OpenAI, scale-ups) and in large enterprises building proprietary models. Distinct from AI engineer in its proximity to the model itself. Expect this role to bifurcate: pure research at labs vs. applied fine-tuning at enterprises. + +--- + +## 6. AI Agent Engineer + +**Status**: High growth — one of the most in-demand specialized roles in 2025-2026. + +### What they do + +Design and build autonomous agent systems. While AI engineers build general AI products, agent engineers specialize in systems that plan, reason, use tools, and execute multi-step tasks without constant human intervention. + +### Responsibilities + +- Design multi-agent architectures (orchestrator + specialist agents) +- Build agent memory systems (short-term, long-term, episodic) +- Implement tool use and API integrations for agents +- Design guardrails and safety mechanisms for autonomous systems +- Build human-in-the-loop checkpoints for high-risk decisions +- Monitor agent behavior in production (reliability, cost, anomaly detection) +- Test agent systems systematically (agentic eval is a distinct discipline) + +### Required skills + +| Technical | Soft | +|-----------|------| +| Agent frameworks (LangChain, AutoGen, Claude Agent SDK, CrewAI) | Systems thinking | +| Orchestration patterns | Risk judgment (when to let agents act autonomously) | +| Tool/API integration | User experience intuition | +| Async programming | Debugging patience (agents fail in non-deterministic ways) | +| Observability and tracing (LangSmith, Langfuse, etc.) | | + +### Key challenge specific to this role + +Non-determinism. Agent systems fail in ways that are hard to reproduce. Observability tooling (tracing every agent step) is as critical as the agent code itself. Engineers who treat agent debugging like debugging traditional code struggle. + +--- + +## 7. Founding AI Engineer + +**Status**: Highly sought after in AI-native startups and seed-to-Series A companies. + +### What they do + +A hybrid role unique to early-stage companies: part AI engineer, part product engineer, part technical co-founder. They own core product functionality end-to-end, from architecture decisions to customer interactions, while building on top of AI capabilities. + +> Typically targets engineers with 0-4 years of experience who are comfortable with ambiguity, figure things out independently, and already use AI tools daily in their workflow. + +### Responsibilities + +- Build entire product features from architecture to deployment, not just assigned tickets +- Make foundational technical decisions that will shape the company's stack for years +- Work directly with founders on product strategy and prioritization +- Use AI coding tools as force multipliers to ship at startup speed +- Interact directly with early customers to understand problems +- Define engineering culture before it calcifies + +### What makes this role different + +Scope of ownership and ambiguity. A senior engineer at a large company works within defined systems. A founding engineer defines the systems. The leverage is massive in both directions: great decisions compound, bad ones become technical debt that's hard to escape. + +### Required profile + +- Bias toward action over analysis paralysis +- Comfort shipping imperfect things and iterating +- Product intuition alongside technical skills +- Already fluent with AI coding tools (Claude Code, Cursor, Copilot) +- Able to context-switch from infra to product to customer research in the same day + +### Entry paths + +Strong mid-level engineers at established companies who want more ownership. Common source: engineers who've been quietly building side projects with AI tools. + +--- + +## 8. AI Architect + +**Status**: Senior/Staff level — emerging role in larger organizations. + +### What they do + +Design enterprise AI systems at the system level. Where AI engineers ship features, AI architects define the patterns, platforms, and decision frameworks that multiple teams use. They make the technology choices that others live with for years. + +### Responsibilities + +- Define AI technology strategy and stack decisions (which models, which frameworks, which providers) +- Design enterprise AI reference architectures +- Set standards for AI system observability, security, and governance +- Evaluate build vs. buy decisions for AI capabilities +- Ensure AI systems are scalable, cost-effective, and auditable +- Bridge between business requirements and technical AI implementation + +### Required skills + +- Deep experience across AI/ML stack (models, infrastructure, MLOps) +- Strong communication skills (presenting to C-suite, working with legal/compliance) +- Understanding of cloud provider AI offerings (AWS Bedrock, Azure OpenAI, Vertex AI) +- Security and compliance awareness (GDPR, AI Act, SOC2) +- Experience designing distributed systems at scale + +### Entry paths + +Senior AI engineer → Staff → Architect. Often takes 5-8 years in AI-adjacent roles. Alternatively: cloud architect + strong AI self-study. + +--- + +## 9. Platform Engineer (AI context) + +**Status**: Established role, significantly reshaped by AI. + +### What they do + +Build and maintain the internal developer platform. With AI, this role has expanded to include the "golden path" for AI development: standardized ways for teams to integrate LLMs, common observability infrastructure, cost controls, and guardrails so individual teams don't reinvent the wheel or create security risks. + +### AI-specific responsibilities added to traditional platform work + +- Provide standardized LLM integration patterns (internal SDKs, proxies, abstractions) +- Manage API keys, rate limits, and cost allocation across teams +- Build AI observability infrastructure (tracing, logging, alerting) +- Enforce security policies for AI outputs (PII filtering, output validation) +- Maintain model registries and versioning systems +- Create "paved roads" for RAG patterns, agent architectures, eval pipelines + +### Why this role matters more with AI + +When every team is building their own LLM integrations, you get: duplicated cost, inconsistent security, no centralized observability, and no shared learnings. Platform engineers who understand AI prevent this fragmentation. They're the reason the AI investment in a company scales instead of sprawling. + +### Required skills (AI additions) + +MLOps tooling, LLM gateway products (LiteLLM, Portkey), cloud AI services, cost optimization patterns, security for AI (prompt injection mitigation, output filtering). + +--- + +## 10. Harness Engineer + +**Status**: Emerging — formalized by Martin Fowler in 2025, not yet institutionalized as a standalone title. + +### What they do + +Build the infrastructure that keeps AI agents "under harness" — under control. As agentic AI systems generate code, take actions, and operate with increasing autonomy, harness engineers build the systems that ensure they stay within architectural constraints, produce coherent output, and don't accumulate entropy over time. + +> Source: [Martin Fowler — Harness Engineering](https://martinfowler.com/articles/exploring-gen-ai/harness-engineering.html) + +### The three pillars + +**1. Context engineering (knowledge infrastructure)** +Not one-off prompts, but a continuously updated knowledge base embedded in the codebase. Agents know your conventions, architecture decisions, and domain context. Dynamic access to observability data and documentation. + +**2. Architectural constraints (agent guardrails)** +- LLM-based watchdog agents that review generated code +- Custom deterministic linters enforcing your specific architectural patterns +- Structural tests (ArchUnit-style) that run automatically +- Pre-commit hooks that reject code violating established constraints + +**3. Entropy management (drift prevention)** +Periodic agents that scan the codebase for: outdated documentation, architectural violations that slipped through, abandoned patterns that reappeared, inconsistencies introduced by multiple agents working in parallel. + +### The core insight + +Without a harness, AI agents produce code that individually looks fine but collectively drifts away from your architecture, your patterns, and your documentation. The harness is what makes "AI generates most of the code" sustainable at scale rather than a path to unmaintainable systems. + +### Organizational impact + +This role pushes toward **intentional technological convergence**: organizations with 2-3 primary tech stacks benefit far more from standardized harnesses than organizations with 10 different stacks. It's a deliberate trade of technical freedom for reliability. + +> "Ce n'est pas quelque chose dans lequel vous pouvez vous lancer pour des résultats rapides." — Martin Fowler + +### Where this role will emerge + +Currently absorbed by: platform engineers, staff/principal engineers, architecture guilds. Likely to become an explicit role in: +- Companies running autonomous coding agents at scale +- Large enterprises with 50+ engineers using AI coding tools +- Organizations that've experienced "AI entropy" firsthand (code that works but nobody understands anymore) + +### Required skills + +Software architecture, linter/static analysis tooling, LLM orchestration, observability, codebase knowledge management, entropy detection patterns. + +--- + +## 11. AI Product Manager + +**Status**: Mainstream and growing, with significant premium over traditional PM roles. + +### What they do + +Product management with deep AI fluency. They understand what AI can and can't do, manage the unique product challenges of AI systems (non-determinism, latency, hallucinations, cost), and translate between business needs and AI capabilities. + +### Responsibilities + +- Define product requirements for AI features with technical constraints in mind +- Work with AI engineers on evaluation criteria (what does "good" look like?) +- Manage the unique UX challenges of AI: uncertainty, latency, error handling +- Own the cost/quality/speed tradeoffs for AI features +- Communicate AI limitations and risks to stakeholders +- Run A/B tests on model versions, prompt changes, feature changes + +### What makes AI PM different from traditional PM + +Traditional PM ships features that behave deterministically. AI PMs ship systems where outputs vary. They need to think probabilistically: not "will this work?" but "what % of the time will this work, and what happens in the other cases?" Quality measurement is continuous, not binary. + +### Required skills + +Standard PM skills (roadmapping, prioritization, user research) plus: LLM API familiarity, eval design, basic Python for running experiments, understanding of model tradeoffs (accuracy vs. cost vs. latency), AI UX patterns. + +### Salary context + +FAANG-level: $160K-$200K+ entry-level AI PM. Senior: $200K-$300K+ total compensation. + +--- + +## 12. AI Safety & Eval Engineer + +**Status**: Specialized — primarily at AI labs and companies with regulated AI deployments. + +### What they do + +Ensure AI systems behave safely, reliably, and in alignment with intended values. Two related but distinct specializations: **Eval Engineers** (build systems to measure model behavior) and **AI Safety Engineers** (identify and mitigate risks in AI systems). + +### Eval Engineer responsibilities + +- Design evaluation frameworks (evals) to measure model quality, safety, and capabilities +- Build automated eval pipelines that run on every model version change +- Define metrics that capture real-world performance (not just benchmark gaming) +- Implement human evaluation workflows for subjective quality dimensions +- Detect regressions before they reach production + +### AI Safety Engineer responsibilities + +- Red-team AI systems to find failure modes, jailbreaks, and harmful outputs +- Implement content filtering, output validation, and guardrail systems +- Design human-in-the-loop checkpoints for high-risk decisions +- Monitor production systems for harmful outputs or unexpected behavior +- Work with legal/compliance on AI governance + +### Required skills + +Rigorous experimental design, statistics, Python, strong understanding of LLM failure modes, communication skills for risk reporting. + +### Where to find these roles + +Primarily: Anthropic, OpenAI, Google DeepMind, Meta AI, Microsoft AI. Growing in: healthcare, finance, legal tech — regulated industries where AI errors have serious consequences. + +--- + +## 13. ML Engineer + +**Status**: Established — the most traditional of the AI engineering roles. + +### What they do + +Develop, train, deploy, and maintain machine learning models. In the LLM era, many ML engineers have pivoted toward fine-tuning and applied AI work rather than building models from scratch — that work is increasingly concentrated at a small number of frontier labs. + +### Responsibilities + +- Data pipeline development (collection, cleaning, transformation) +- Model training and fine-tuning +- Feature engineering +- Model serving and deployment (MLOps) +- Performance optimization and model compression +- Production monitoring for model drift + +### How the role is evolving + +The "build a model from scratch" path is increasingly rare outside frontier labs. ML engineers in most companies now work on: fine-tuning existing models, building RAG systems, deploying and monitoring models in production, and bridging between AI engineers and data infrastructure. The practical overlap with AI engineer is large. + +### Required skills + +Python (fluent), PyTorch or TensorFlow, distributed computing, data pipeline tools (Spark, Airflow, dbt), cloud ML platforms (SageMaker, Vertex AI, Azure ML), statistical foundations. + +--- + +## 14. Career Decision Matrix + +Which role fits your current background and goals? + +| Your current profile | Best next role | Timeline | +|---------------------|---------------|----------| +| Software engineer (3+ years) who wants to work with AI | AI Engineer | 3-6 months upskill | +| Software engineer at early startup who wants ownership | Founding AI Engineer | Now, if opportunity exists | +| Backend engineer interested in infra + AI | Platform Engineer (AI) | 6-12 months | +| Senior engineer who thinks in systems | AI Architect or Harness Engineer | 1-2 years experience accumulation | +| Engineer who likes research and rigor | LLM Engineer or AI Safety/Eval | +ML foundations needed | +| Non-technical who works with AI daily | Prompt Engineer → Context Engineer | 6-18 months | +| PM who wants to stay PM but be more relevant | AI Product Manager | 3-6 months upskill | +| Engineer obsessed with reliability and architecture | Harness Engineer (emerging) | Pioneers' territory | + +### The fastest path to AI employment in 2025-2026 + +1. Build something with AI APIs (Claude, OpenAI) — a real project, not a tutorial +2. Write about what you built (blog post, GitHub README, LinkedIn) +3. Add evaluation: measure your system's quality, show the numbers +4. Apply for AI Engineer roles — the bar is demonstrated building, not credentials + +Note: 76% of candidates claiming AI expertise lack production-level deployment experience (LangChain State of Agent Engineering 2025). The bar is lower than it appears if you've actually shipped something. + +--- + +## 15. Salary Benchmarks (2025-2026) + +These are US market figures. Expect 30-50% lower in Europe, 40-60% lower in other markets. + +| Role | Entry | Mid | Senior | Notes | +|------|-------|-----|--------|-------| +| Prompt Engineer | $80K-$110K | $110K-$150K | $150K-$180K | Shrinking standalone market | +| Context Engineer | $100K-$140K | $140K-$180K | $180K-$230K | Growing fast | +| AI Engineer | $120K-$160K | $160K-$220K | $220K-$300K | Highest volume of open roles | +| LLM Engineer | $130K-$170K | $170K-$250K | $250K-$350K | Lab-level roles higher | +| AI Agent Engineer | $130K-$170K | $170K-$240K | $240K-$320K | Strong demand 2025-2026 | +| Founding AI Engineer | $100K-$150K + equity | — | — | Equity makes total comp wide-ranging | +| AI Architect | — | $180K-$260K | $260K-$380K | Senior/Staff only | +| Platform Engineer (AI) | $110K-$150K | $150K-$210K | $210K-$280K | | +| Harness Engineer | Not yet standardized | — | — | Absorbed into other roles | +| AI Product Manager | $130K-$170K | $170K-$230K | $230K-$350K | FAANG premium significant | +| AI Safety/Eval Engineer | $140K-$180K | $180K-$250K | $250K-$400K | Lab compensation highest | +| ML Engineer | $100K-$140K | $140K-$200K | $200K-$280K | Lower demand outside labs | + +> **Sources**: FinalRoundAI (2025), Alcor AI Salary Report (2025), RiseWorks AI Talent Report (2025), job postings analysis. + +--- + +## 16. What's Not a Role (Yet) + +Some terms you'll hear that describe practices or methodologies, not job titles: + +**Vibe coder** — A methodology (use AI coding assistants to handle implementation while you focus on design), not a job. Andrej Karpathy coined the term then himself pivoted toward "context engineering" as more precise. No serious company has "Vibe Coder" on a job description. + +**AI-native engineer** — Describes a quality expected of all engineers increasingly, not a specialized role. It means: you use AI tools fluently in your daily workflow. It's the bar, not the title. + +**Orchestration engineer** — Sometimes used for agent systems, overlaps significantly with AI Agent Engineer. Not yet a distinct category. + +These terms are worth knowing (you'll encounter them in job descriptions and articles) but don't represent distinct career paths — yet. + +--- + +## 17. Job Listings + +> **Coming soon** — Curated listings for AI roles at companies building seriously with Claude Code and agentic AI. + +If you're hiring for any of the roles described in this guide, [reach out](https://florian.bruniaux.com) to discuss featuring your opportunity here. + +--- + +## 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 diff --git a/guide/learning-with-ai.md b/guide/learning-with-ai.md index ebd873c..6776baa 100644 --- a/guide/learning-with-ai.md +++ b/guide/learning-with-ai.md @@ -1104,6 +1104,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 - [Workflows: Spec-First](./workflows/spec-first.md) — Understand requirements before code - [Workflows: Plan-Driven](./workflows/plan-driven.md) — Use /plan mode for complex work