From 98f0c87806a5f53afb9886ac6135da60ecaad5f8 Mon Sep 17 00:00:00 2001 From: Florian BRUNIAUX Date: Mon, 9 Mar 2026 10:57:12 +0100 Subject: [PATCH] feat(docs): add persona sub-READMEs + routing table in README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add 4 audience-specific entry points in docs/: - for-tech-leads.md — team adoption, shared config, security posture - for-cto.md — ROI, compliance, adoption path - for-cio-ceo.md — 3-min brief, budget, 3 questions for your CTO - for-product-managers.md — vibe coding, working with AI-assisted teams Add visual routing table in README ("Not a developer?") linking to each. Mark whitepapers as coming soon throughout. Co-Authored-By: Claude Sonnet 4.6 --- README.md | 4 +- docs/for-cio-ceo.md | 87 ++++++++++++++++++++++++++++ docs/for-cto.md | 107 +++++++++++++++++++++++++++++++++++ docs/for-product-managers.md | 85 ++++++++++++++++++++++++++++ docs/for-tech-leads.md | 100 ++++++++++++++++++++++++++++++++ 5 files changed, 381 insertions(+), 2 deletions(-) create mode 100644 docs/for-cio-ceo.md create mode 100644 docs/for-cto.md create mode 100644 docs/for-product-managers.md create mode 100644 docs/for-tech-leads.md diff --git a/README.md b/README.md index 40d5af8..bf9fa72 100644 --- a/README.md +++ b/README.md @@ -543,6 +543,8 @@ security_gate_hook: "examples/hooks/bash/security-gate.sh" # file path ref A series of 9 focused whitepapers covering Claude Code in depth. Each covers a specific topic and is available in both **French and English**. +> **Coming soon** — currently in private access. Public release planned. + - **00** — *De Zéro à Productif / From Zero to Productive* — Foundations, first steps - **01** — *Prompts qui Marchent / Prompts That Work* — Prompting method, context, hooks - **02** — *Personnaliser Claude / Customizing Claude* — CLAUDE.md, custom agents, skills @@ -553,8 +555,6 @@ A series of 9 focused whitepapers covering Claude Code in depth. Each covers a s - **07** — *Guide de Référence / Reference Guide* — Complete synthesis + advanced workflows - **08** — *Agent Teams* — Multi-agent orchestration and coordination -→ **[Download all whitepapers](https://www.florian.bruniaux.com/guides)** - --- ## 🌍 Ecosystem diff --git a/docs/for-cio-ceo.md b/docs/for-cio-ceo.md new file mode 100644 index 0000000..3be6b60 --- /dev/null +++ b/docs/for-cio-ceo.md @@ -0,0 +1,87 @@ +# Claude Code — For CIOs & CEOs + +> 3 minutes. What you need to know about Claude Code before your next meeting with your CTO or CIO. + +--- + +## What it is (in one sentence) + +Claude Code is an AI assistant that runs directly in your developers' environment — it reads code, writes code, runs tests, and does code review, autonomously or under supervision. + +This is not a chatbot. It's a production tool. + +--- + +## Why it matters to you + +**Your competitors are already using it.** 91% of tech organizations have adopted at least one AI tool in their engineering workflow (Stack Overflow 2025). The question is no longer "should we adopt?" — it's "are we doing it right?" + +**The advantage comes from structure, not from the tool itself.** A team with a shared configuration, documented business rules, and security guardrails is 3 to 5× more effective than a team using the same tools without a framework. The competitive edge comes from organizational discipline, not from the license. + +**The risk of doing nothing is greater than the risk of adoption.** Your developers are probably already using it informally. Without a clear policy, you have security exposure without the benefit of measurable productivity gains. + +--- + +## The numbers + +| Indicator | Value | +|-----------|-------| +| Cost per developer | $100/month (Claude Max plan) | +| Time to ROI | < 1 week at $700-900/day loaded cost | +| Observed gains on routine tasks | 30-50% (tests, boilerplate, documentation, review) | +| Structured adoption timeline | 4-6 weeks for a team | +| Risk of unstructured adoption | Security exposure + quality debt | + +--- + +## 3 questions to ask your CTO + +1. **"Are our developers already using it?"** — The answer is probably yes. The real question is: with what configuration, what rules, and what level of traceability? + +2. **"Do we have a policy on what can be sent to the AI?"** — Config files, API keys, customer data: everything that goes into a prompt is sent to Anthropic's servers. This risk is manageable, but only if a policy exists. + +3. **"Who is our internal champion?"** — The teams that succeed have a tech lead or senior engineer dedicated to structuring adoption. This doesn't require a new headcount — it takes 10-15% of someone already in place. + +--- + +## What it actually costs + +**License**: $100/month per developer (Claude Max). For a team of 10, that's $1,000/month — less than 2 days of external consulting. + +**Training**: one structured day is enough for a team of 10 to 15 people. A free Brown Bag Lunch (1h) lets you test team interest before committing to anything. + +**Doing nothing**: your developers use unvetted free tools, with no data policy, no audit trail. That scenario carries more risk than structured adoption. + +--- + +## What you can delegate (and to whom) + +| Decision | You | Your CTO/CIO | External expert | +|----------|-----|-------------|-----------------| +| License budget | ✅ | — | — | +| Data policy / GDPR | ✅ validation | ✅ drafting | ✅ audit | +| Team configuration | — | ✅ | ✅ if needed | +| Training | — | ✅ identification | ✅ if structured | +| Results measurement | ✅ validation | ✅ definition | — | + +--- + +## Concrete next step + +**Option 1 — You want to understand before deciding**: ask your CTO for a 30-minute demo on a real use case from your codebase. + +**Option 2 — You want to move fast**: a free Brown Bag Lunch (1h, in-person or remote) covers the fundamentals for your executive and technical teams simultaneously. + +**Option 3 — You already have teams using it**: a configuration audit (half-day) identifies active risks and optimization opportunities. + +→ [Contact Florian Bruniaux](https://florianbruniaux.github.io/claude-code-ultimate-guide-landing/) — availability and pricing + +--- + +## Going further (if you want the details) + +- WP06 — Privacy & GDPR Compliance *(whitepaper, coming soon)* — what goes to Anthropic, how to control it +- WP03 — Security in Production *(whitepaper, coming soon)* — CVE database, attack vectors, mitigation +- WP05 — Deploying with a Team *(whitepaper, coming soon)* — adoption phases, governance, ROI + +← [Back to main README](../README.md) diff --git a/docs/for-cto.md b/docs/for-cto.md new file mode 100644 index 0000000..3d8d1c5 --- /dev/null +++ b/docs/for-cto.md @@ -0,0 +1,107 @@ +# Claude Code — For CTOs & Decision Makers + +> Your engineering team is probably already using AI coding tools. The question isn't whether to adopt Claude Code — it's whether to do it in a controlled, secure, measurable way or let it happen organically (which means inconsistently). + +--- + +## The business case in 3 data points + +- **62-85%** of developers already use AI coding tools daily (Stack Overflow 2025) +- **91%** of organizations have adopted at least one AI tool in their engineering workflow +- Teams with structured Claude Code adoption report **30-50% reduction** in routine coding tasks (config, boilerplate, test generation, code review) + +The gap isn't adoption — it's structured adoption. Most teams are using 10% of what Claude Code can do. + +--- + +## What decision makers need to know + +### Security & Compliance + +Claude Code runs locally. It does **not** send your codebase to Anthropic — only the specific context you include in a prompt. What matters for compliance: + +- Data retention: configurable (0 to 30 days), or disabled +- GDPR: clear opt-out path, no training on your data by default +- Access control: granular permissions per project, per user, per tool +- Audit trail: every action logged via hooks + +Full breakdown: WP06 — Privacy & GDPR Compliance *(whitepaper, coming soon)* (20 min) + +### Threat landscape + +This is the only public resource tracking AI coding tool CVEs: **24 vulnerabilities and 655 malicious skills catalogued**. Key vectors relevant to enterprise: + +- Prompt injection via untrusted file content (e.g. malicious comments in dependencies) +- Supply chain attacks via MCP servers (treat like npm packages) +- Overpermissive configs in CI/CD pipelines + +Mitigation framework: WP03 — Security in Production *(whitepaper, coming soon)* (25 min) + +### Team adoption + +The ROI scales with structure. An individual developer gets 2-3× productivity on routine tasks. A team with shared configuration, hooks, and standardized workflows gets more, with consistent quality and security posture. + +Realistic adoption timeline: 4-6 weeks to full team competency with structured onboarding. + +WP05 — Deploying with a Team *(whitepaper, coming soon)* (25 min) + +--- + +## Recommended reading path (60 min total) + +> Whitepapers are currently in private access — public release coming soon. + +| Document | Time | What you'll get | +|----------|------|----------------| +| WP06 — Privacy & GDPR | 20 min | Data flows, retention policy, compliance checklist | +| WP03 — Security | 25 min | Threat model, CVE database, mitigation framework | +| WP05 — Team Deployment | 25 min | Adoption phases, ROI, governance | + +--- + +## The adoption path that works + +Most teams that succeed follow the same sequence: + +**1. Pilot (2-3 devs, 2 weeks)** +Identify 2-3 motivated engineers. Let them configure and experiment. Measure time saved on specific tasks (code review, test generation, documentation). + +**2. Config standardization (1 week)** +Tech lead or external expert reviews their setup. Creates a shared `CLAUDE.md` for the team. Adds security hooks and CI/CD integration. Documents "what's allowed, what's not." + +**3. Team rollout (2-3 weeks)** +1h onboarding session for the full team. Champions support peers. Shared config versioned in the repo. + +**4. Governance** +Monthly review of usage patterns, cost, and security posture. Adjust permissions as AI capabilities evolve. + +--- + +## Costs + +Claude Code subscription: $100/month per developer (Claude Max plan, includes full API access). + +At a loaded developer cost of €500-700/day, recovering 30 minutes per day per developer pays back the subscription in week 1. + +The real cost isn't the subscription — it's unstructured adoption creating security debt and inconsistent output quality. + +--- + +## External support + +If you want to accelerate adoption or get an independent assessment of your current setup: + +**Brown Bag Lunch (1h, free)** — executive + team intro, live demo, Q&A +**Config audit (half-day)** — review your current setup against security and productivity standards +**Team formation (1-3 days)** — hands-on training, your codebase, your workflows, measurable outcomes + +→ [Contact Florian Bruniaux](https://florianbruniaux.github.io/claude-code-ultimate-guide-landing/) for availability and pricing + +--- + +## Quick links + +- Whitepapers — 10 focused deep-dives *(coming soon)* +- [Security Hardening Guide](../guide/security-hardening.md) + +← [Back to main README](../README.md) diff --git a/docs/for-product-managers.md b/docs/for-product-managers.md new file mode 100644 index 0000000..bd58c65 --- /dev/null +++ b/docs/for-product-managers.md @@ -0,0 +1,85 @@ +# Claude Code — For Product Managers & Product Designers + +> You don't need to become a developer to get value from Claude Code. But understanding what it does — and what it can do for you directly — changes how you work with your team and what you can ship yourself. + +--- + +## Two distinct use cases + +**1. You work alongside developers who use Claude Code** +Understanding the tool helps you write better specs, unblock faster, and have more grounded conversations about effort and trade-offs. + +**2. You want to use it yourself** +"Vibe coding" is real. PMs are increasingly prototyping features, writing scripts, and generating data analyses without a developer. Claude Code makes this accessible if you're willing to learn the basics. + +--- + +## If you work with developers who use Claude Code + +### What changes for your workflow + +**Specs become context** — Your PRD, acceptance criteria, and edge cases can live in a `CLAUDE.md` file at the root of a feature branch. The developer's Claude Code instance reads it automatically. Better specs = less back-and-forth. + +**You can review AI-assisted work** — When a developer says "Claude wrote most of this," you can ask Claude Code to explain what was generated, why, and what the trade-offs are. No code reading required. + +**Velocity expectations shift** — Boilerplate, tests, documentation, migrations: these take a fraction of the time with Claude Code. If your sprint estimates still reflect pre-AI effort, they're wrong. + +### The one thing worth reading + +WP05 — Deploying with a Team *(whitepaper, coming soon)* — specifically the adoption phases section. Understanding the Champion → Pilot → Team rollout pattern helps you plan feature releases that depend on the team being productive with AI tooling. + +--- + +## If you want to use Claude Code yourself + +### What you can do without coding experience + +- **Prototype a feature** — describe what you want, Claude Code generates a working demo +- **Query your data** — write SQL or Python scripts by describing what you need in plain language +- **Automate repetitive tasks** — Excel → CSV → formatted report, without asking a developer +- **Generate test cases** — paste an acceptance criteria, get a test suite +- **Understand existing code** — "What does this function do?" works better than Stack Overflow for your codebase + +### What you actually need to get started + +1. Install Claude Code (5 min) → [Guide Ch.1.1](../guide/ultimate-guide.md#11-installation) +2. Learn the one prompt formula → [Guide Ch.2.8 — Structured Prompting](../guide/ultimate-guide.md#28-structured-prompting-with-xml-tags) +3. Understand how to give it context → [Guide Ch.3.1 — CLAUDE.md](../guide/ultimate-guide.md#31-memory-files-claudemd) + +That's it for the first week. + +### The learning curve is real — here's how to manage it + +WP09 — Learning with AI (UVAL Protocol) *(whitepaper, coming soon)* was written specifically for this. The UVAL framework (Understand / Verify / Apply / Learn) is a structured approach to building real competency rather than copy-pasting outputs you don't understand. + +Key insight: **comprehension debt** is the risk. Using Claude Code to ship features you don't understand creates fragility. The protocol helps you stay in control. + +--- + +## What's NOT for you in this guide + +This guide is primarily for developers. Most of chapters 4-9 (Agents, Skills, Hooks, MCP, Advanced Patterns) will be irrelevant to you unless you're going deep. + +For general Claude productivity (writing, research, analysis, meeting prep): +→ **[Claude Cowork Guide](https://github.com/FlorianBruniaux/claude-cowork-guide)** — designed specifically for non-developers + +--- + +## Recommended reading (30 min) + +| Document | Time | If you're... | +|----------|------|-------------| +| WP09 — Learning with AI *(coming soon)* | 30 min | Considering using CC yourself | +| [Guide Ch.1.1-1.3](../guide/ultimate-guide.md#11-installation) | 20 min | Ready to install and try | +| WP05 — Team Deployment *(coming soon)* | 25 min | Working with a dev team that uses CC | + +--- + +## Quick links + +- [Claude Cowork Guide](https://github.com/FlorianBruniaux/claude-cowork-guide) — for non-dev Claude usage +- WP09 — Learning with AI *(coming soon)* +- [Guide Ch.1 — Quick Start](../guide/ultimate-guide.md#1-quick-start-day-1) +- [Cheatsheet](../guide/cheatsheet.md) — daily reference once you're started + +← [Back to main README](../README.md) diff --git a/docs/for-tech-leads.md b/docs/for-tech-leads.md new file mode 100644 index 0000000..668cb22 --- /dev/null +++ b/docs/for-tech-leads.md @@ -0,0 +1,100 @@ +# Claude Code — For Tech Leads & Engineering Managers + +> You've probably heard your devs talk about Claude Code. Maybe some are already using it. This page is for you — the person responsible for making that adoption consistent, secure, and scalable across the team. + +--- + +## The core problem + +Left to their own devices, each developer builds their own Claude Code setup. Different CLAUDE.md files, different permission configs, no shared hooks, no observability. The productivity gains are real but chaotic, and the security surface grows unchecked. + +A team with a shared configuration is 3-5× more effective than the same devs working with individual setups. + +--- + +## What you get from this guide + +| Your concern | What's covered | +|---|---| +| **Standardizing config across the team** | WP05 — Deploying with a Team *(coming soon)* | +| **Security & compliance** | WP03 — Security in Production · WP06 — Privacy & GDPR *(coming soon)* | +| **CI/CD integration** | [Guide Ch.9.3](../guide/ultimate-guide.md#93-cicd-integration) | +| **Onboarding new devs** | [Guide Ch.3.5 — Team Configuration at Scale](../guide/ultimate-guide.md#35-team-configuration-at-scale) | +| **Understanding the architecture** | WP04 — Architecture Demystified *(coming soon)* | +| **Multi-agent workflows** | WP08 — Agent Teams *(coming soon)* | + +--- + +## 30-minute reading path + +> Whitepapers are currently in private access — public release coming soon. + +1. **WP05 — Deploying with a Team** *(coming soon)* (25 min) + - CLAUDE.md hierarchy (global / project / local) + - Champions program: how to identify and empower early adopters + - GitHub Actions for automated review + security scanning + - Adoption phases: pilot → expansion → generalization + +2. **[Guide Ch.3.5 — Team Configuration at Scale](../guide/ultimate-guide.md#35-team-configuration-at-scale)** (5 min) + - How to version your team config in the repo + - Shared vs personal settings + +--- + +## The 3 things to do this week + +**1. Version your CLAUDE.md in the repo** +Create a `CLAUDE.md` at the root of your main repo. It applies to everyone on the team automatically. Start with coding conventions, architecture decisions, and "never do X" rules. + +**2. Identify one champion** +One engineer who's already effective with Claude Code. Give them time to document their setup and run a 1h team session. + +**3. Add one security hook** +The minimum: a pre-tool hook that blocks writes to `.env` files and `**/secrets/**` paths. Takes 10 minutes to set up, covers a real threat vector. + +```bash +# Example: hooks/block-sensitive-files.sh +if [[ "$TOOL_INPUT_PATH" =~ \.env$|secrets/ ]]; then + echo "BLOCKED: sensitive file path" + exit 2 +fi +``` + +See [Guide Ch.7.4 — Security Hooks](../guide/ultimate-guide.md#74-security-hooks) for the full set. + +--- + +## Security posture overview + +This guide maintains the **only public threat database for Claude Code**: 24 CVEs and 655 malicious skills catalogued. Key risks for teams: + +- **Prompt injection** via untrusted file content or MCP servers +- **Overly permissive settings** — `allowedTools: ["*"]` in production +- **Unvetted MCP servers** — treat them like npm packages (supply chain risk) +- **Missing audit trail** — who did what, when + +Full coverage in WP03 — Security and WP06 — Privacy *(whitepapers, coming soon)*. + +--- + +## Training your team + +If you want structured onboarding rather than self-learning: + +- **Brown Bag Lunch (1h, free)** — intro session covering core concepts + team config live +- **Team formation (1-2 days)** — hands-on, your codebase, your workflows +- **Config audit** — review your current setup against security and productivity best practices + +→ [Contact Florian Bruniaux](https://florianbruniaux.github.io/claude-code-ultimate-guide-landing/) for availability + +--- + +## Quick links + +- [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 +- [CHANGELOG](../CHANGELOG.md) — what changed recently + +← [Back to main README](../README.md)