From 37d9d70ea294ad2885b7f48842904a167d21bf82 Mon Sep 17 00:00:00 2001 From: Florian BRUNIAUX Date: Wed, 4 Mar 2026 17:29:06 +0100 Subject: [PATCH] docs: tech leads section, straude, session-naming, cowork updates MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - guide/learning-with-ai.md: §12 For Tech Leads & Engineering Managers (onboarding 4 semaines, métriques croissance réelle, mentoring scalable, warning signs équipe, template politique AI) - guide/third-party-tools.md: fiche straude (dashboard social CC, analyse sécu) - examples/claude-md/session-naming.md: template auto-rename sessions - guide/cowork.md: mise à jour contenu et comparaisons - docs/resource-evaluations/: +2 évaluations (eveillard, straude) - README.md + examples/README.md: compteurs templates 175→176 - machine-readable/reference.yaml: nouvelles entrées Co-Authored-By: Claude Sonnet 4.6 --- README.md | 12 +- .../2026-03-04-eveillard-generation-llm.md | 76 +++++++ docs/resource-evaluations/README.md | 1 + .../straude-evaluation.md | 192 ++++++++++++++++++ examples/README.md | 5 +- examples/claude-md/session-naming.md | 87 ++++++++ guide/cowork.md | 31 ++- guide/learning-with-ai.md | 149 +++++++++++++- guide/third-party-tools.md | 43 ++++ machine-readable/reference.yaml | 6 + 10 files changed, 581 insertions(+), 21 deletions(-) create mode 100644 docs/resource-evaluations/2026-03-04-eveillard-generation-llm.md create mode 100644 docs/resource-evaluations/straude-evaluation.md create mode 100644 examples/claude-md/session-naming.md diff --git a/README.md b/README.md index 5927723..0a41866 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ Stars Last Update Quiz - Templates + Templates Threat Database MCP Server

@@ -52,7 +52,7 @@ Both guides serve different needs. Choose based on your priority. | **Security hardening** | Only threat database (24 CVEs) | Basic patterns only | | **Test understanding** | 274-question quiz | Not available | | **Methodologies** (TDD/SDD/BDD) | Full workflow guides | Not covered | -| **Copy-paste ready** templates | 175 templates | 200+ templates | +| **Copy-paste ready** templates | 176 templates | 200+ templates | ### Ecosystem Positioning @@ -137,7 +137,7 @@ graph LR root[📦 Repository
Root] root --> guide[📖 guide/
20K lines] - root --> examples[📋 examples/
175 templates] + root --> examples[📋 examples/
176 templates] root --> quiz[🧠 quiz/
274 questions] root --> tools[🔧 tools/
utils] root --> machine[🤖 machine-readable/
AI index] @@ -168,7 +168,7 @@ graph LR │ ├─ mcp-servers-ecosystem.md Official & community MCP servers │ └─ workflows/ Step-by-step guides │ -├─ 📋 examples/ 175 Production Templates +├─ 📋 examples/ 176 Production Templates │ ├─ agents/ 9 custom AI personas │ ├─ commands/ 26 slash commands │ ├─ hooks/ 31 hooks (bash + PowerShell) @@ -289,7 +289,7 @@ Complete guides with rationale and examples: --- -### 📚 175 Annotated Templates +### 📚 176 Annotated Templates **Outcome**: Learn patterns, not just configs. @@ -721,7 +721,7 @@ Use this guide critically. Experiment. Share what works for you. | **[Claude Code Releases](./guide/claude-code-releases.md)** | Official release history | 10 min |
-Examples Library (175 templates) +Examples Library (176 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) ⭐ diff --git a/docs/resource-evaluations/2026-03-04-eveillard-generation-llm.md b/docs/resource-evaluations/2026-03-04-eveillard-generation-llm.md new file mode 100644 index 0000000..6c46e92 --- /dev/null +++ b/docs/resource-evaluations/2026-03-04-eveillard-generation-llm.md @@ -0,0 +1,76 @@ +# Resource Evaluation: Mathieu Eveillard — "Génération LLM : sale temps pour les juniors" + +**Date**: 2026-03-04 +**Source**: LinkedIn post + https://www.mathieueveillard.com/blog/generation-llm +**Type**: Opinion editorial (blog/LinkedIn) +**Author**: Mathieu Eveillard — Software quality expert, France +**Score**: 2/5 + +--- + +## Summary + +Opinion piece arguing junior developers are not building foundational skills because they over-delegate to LLMs. Core thesis: you can't outsource the cognitive effort of learning. Responsibility for structured mentoring falls on experienced developers and organizations. "It works" is not sufficient — developers must understand architecture, modularization, and testing to use AI responsibly. + +Key claims: +- Juniors use LLMs without the prerequisite knowledge to evaluate output quality +- LLMs are neutral tools; the problem is the absence of method and architectural knowledge +- Experienced developers and organizations must structure "compagnonnage" (apprenticeship) to transmit fundamentals +- Architecture decisions (hexagonal, modularization) have no visible user impact but change everything about maintainability + +--- + +## Score Justification + +**2/5 — Does not integrate directly. Reveals a gap worth filling.** + +The article provides a narrative, opinion-based version of a diagnostic that the guide already covers with more rigor and data (Shen & Tamkin 2026, METR RCT, DORA). It validates our existing work but adds no research or actionable frameworks. + +What it *does* reveal: the guide had no section for tech leads or engineering managers responsible for structuring team-level learning. The article points at that gap without filling it. + +--- + +## Gap Identified → Action Taken + +**Gap**: `guide/learning-with-ai.md` was entirely written for individual developers. No content for the person responsible for onboarding policy, mentoring structure, or team-level AI governance. + +**Action**: Added new section "For Tech Leads & Engineering Managers" (§12) to `guide/learning-with-ai.md`, covering: +- Structured onboarding (4-week model, not "here's your license") +- Metrics for real growth vs. velocity +- Three scalable mentoring models (pair rotations, architecture hot seat, collective CLAUDE.md ownership) +- Team-level CLAUDE.md policy template +- Warning signs at team level with specific responses +- Quick checklist + +Research validated with Perplexity: +- Create Future (2025): structured AI training raises junior savings from 14-42% to 35-65% +- Stanford Digital Economy Study (2025): 22-25 age group employment down ~20% by July 2025 +- LeadDev (2025): tech CEO perspectives on structured junior development in AI teams + +--- + +## What the Article Does NOT Cover + +- Scalability of compagnonnage past teams of 5-10 +- Empirical support for the labor market claims ("sale temps") +- Any actionable framework (it's diagnostic, not prescriptive) +- Team-level tooling or policy structures + +--- + +## Fact-Check + +| Claim | Status | +|-------|--------| +| LLMs at 20-40€/month | Plausible (Claude/GPT pricing 2026) | +| "Loi de l'Instrument" reference | Correct (Maslow's Law of the Instrument) | +| Article URL functional | SSL error during evaluation — content obtained via LinkedIn post | +| Stats on junior skill degradation | Opinion-based, no study cited | + +--- + +## Decision + +**Do not cite this article as a primary source.** It could be mentioned as a practitioner voice in a section on organizational responsibility, but its anecdotal nature makes it weak compared to existing sources (Shen & Tamkin, METR, Borg et al.) already in the guide. + +The real output of this evaluation was identifying and filling the team lead gap — not integrating the article itself. diff --git a/docs/resource-evaluations/README.md b/docs/resource-evaluations/README.md index 274046b..207f944 100644 --- a/docs/resource-evaluations/README.md +++ b/docs/resource-evaluations/README.md @@ -67,6 +67,7 @@ Les documents de travail bruts (prompts Perplexity, audits clients) restent dans | **Master Claude Code Infographic** (Rakesh Gohel / Aakash Gupta) | 2/5 | **2/5** | ❌ Ne pas intégrer (surface-level, erreur Cursor) | [rakesh-gohel-aakash-gupta-master-claude-code.md](./rakesh-gohel-aakash-gupta-master-claude-code.md) | | **Snyk ToxicSkills** (Supply Chain Audit) | 4/5 | **4/5** | ✅ Intégré (security-hardening.md §1.1, §1.2, §1.5) | [snyk-toxicskills-evaluation.md](./snyk-toxicskills-evaluation.md) | | **System Prompts Opus 4.6** (Official Update) | 2/5 | **2/5** | ⚠️ Watch only (2nd eval, same URL, already covered) | [system-prompts-opus-4-6-update.md](./system-prompts-opus-4-6-update.md) | +| **Straude** (Social usage tracker) | 3/5 | **3/5** | ✅ Intégré (third-party-tools.md, analyse sécurité) | [straude-evaluation.md](./straude-evaluation.md) | | **qmd Token Savings** (Simone Ruggiero, Medium) | 2/5 | **2/5** | ❌ Ne pas intégrer (redundant avec grepai, claims non vérifiables) | [2026-02-14-simone-ruggiero-qmd-token-savings-medium.md](./2026-02-14-simone-ruggiero-qmd-token-savings-medium.md) | | **Rippletide** (AI Reliability Platform) | 2/5 | **2/5** | ⚠️ Watch only (MCP server tiers, claims non vérifiables, pas de traction) | [072-rippletide-ai-reliability-platform.md](./072-rippletide-ai-reliability-platform.md) | diff --git a/docs/resource-evaluations/straude-evaluation.md b/docs/resource-evaluations/straude-evaluation.md new file mode 100644 index 0000000..b553392 --- /dev/null +++ b/docs/resource-evaluations/straude-evaluation.md @@ -0,0 +1,192 @@ +# Évaluation de Ressource: Straude (straude.com) + +**Source**: [straude.com](https://straude.com) / [npm: straude](https://www.npmjs.com/package/straude) +**Type**: Outil communautaire (CLI npm) +**Producteur**: oscar.hong2015@gmail.com (indépendant) +**Date d'analyse**: 2026-03-04 +**Méthode**: Inspection directe du code source (`npm pack straude@0.1.9`, lecture des fichiers compilés) +**Guide cible**: Claude Code Ultimate Guide + +--- + +## 📄 Résumé du contenu + +Straude est un dashboard social pour tracker et partager sa consommation Claude Code. L'outil pousse les stats d'usage locales (tokens, coûts, modèles) vers une plateforme partagée avec leaderboard, streaks, et rang global. + +**Flux technique**: +1. Authentification OAuth via navigateur → token stocké dans `~/.straude/config.json` +2. Collecte via `ccusage daily --json` (outil officiel Claude Code) et `@ccusage/codex` +3. POST des données agrégées sur `https://straude.com/api/usage/submit` + +**Données envoyées au serveur** (par jour): +- Coût en USD +- Tokens : input, output, cache creation, cache read, total +- Modèles utilisés (ex: `claude-sonnet-4-6`, `claude-opus-4-6`) +- Breakdown coût par modèle +- Hash SHA256 des données brutes ccusage +- `device_id` : UUID aléatoire généré à la première utilisation +- `device_name` : hostname de la machine (ex: `prenom-macbook.local`) + +**Ce qui n'est PAS envoyé**: fichiers, code source, conversations, clés API. + +--- + +## 🎯 Score de pertinence: 3/5 (Intégration partielle) + +| Score | Signification | +|-------|---------------| +| 5 | Essentiel - Gap majeur dans le guide | +| 4 | Très pertinent - Amélioration significative | +| **3** | **Pertinent - Complément utile** | +| 2 | Marginal - Info secondaire | +| 1 | Hors scope - Non pertinent | + +### Justification + +Notre guide documente déjà `ccusage` (l'outil de référence) et `ccburn`. Straude couvre un angle différent — le tracking social — qui n'était pas documenté. La pertinence est réelle mais limitée : c'est un outil de niche (leaderboard), encore très jeune (13 jours à la date d'analyse), sans historique de confiance ni politique de confidentialité publiée. + +Le score 3/5 se justifie par: +- Angle unique (social tracking) non couvert ailleurs dans le guide +- Analyse de sécurité disponible et factuelle +- Usage réel possible sans risque majeur identifié +- Maturité insuffisante pour un score plus élevé + +--- + +## 🔍 Analyse de sécurité détaillée + +### Inspection du code source + +Le package a été inspecté directement depuis le registre npm (`npm pack straude@0.1.9`) et les fichiers compilés lus intégralement. Pas d'obfuscation détectée. + +**Architecture** (20 fichiers, 35KB non compressés): + +``` +dist/ +├── index.js # CLI entry point +├── config.js # DEFAULT_API_URL = "https://straude.com" +├── commands/ +│ ├── login.js # OAuth browser-based (poll + token save) +│ ├── push.js # Collecte ccusage + POST /api/usage/submit +│ └── status.js # GET /api/users/me/status +└── lib/ + ├── auth.js # Lecture/écriture ~/.straude/config.json + ├── api.js # fetch() avec Bearer token + ├── ccusage.js # exec("ccusage daily --json") + └── codex.js # exec("npx @ccusage/codex daily --json") +``` + +### Points positifs + +- Token stocké avec permissions `0600` (lecture propriétaire uniquement) +- Pas d'accès au filesystem au-delà de `~/.straude/config.json` +- Pas de daemon ou persistence système (pas de crontab, launchd, systemd) +- Payload limité aux métriques agrégées, cohérent avec la description +- Option `--dry-run` pour inspecter sans envoyer + +### Points de vigilance + +| Risque | Niveau | Détail | +|--------|--------|--------| +| Projet très récent | Moyen | Créé 2026-02-18, 10 versions en 13 jours, pas d'audit externe | +| Hostname envoyé | Faible | `device_name = os.hostname()` → souvent identifiable | +| Pas de politique confidentialité | Moyen | Aucune mention légale sur straude.com à date | +| Données sur serveur tiers | Faible | Coûts et tokens publiés partiellement (rang global) | +| Dépendance transitoire | Faible | Installe `@ccusage/codex@18` via npx sans confirmation explicite | + +### Verdict sécurité + +**Pas de malware ni de comportement malveillant détecté.** Le code est lisible, cohérent, et fait ce qu'il dit. Les risques sont ceux d'un projet indie jeune sans track record : absence de garanties sur la pérennité du service, la gestion des données, et la confidentialité des métriques. + +--- + +## ⚖️ Comparatif avec l'existant + +| Aspect | ccusage | ccburn | Straude | +|--------|---------|--------|---------| +| Tracking local | ✅ Complet | ✅ Visuel | ✅ Via ccusage | +| Partage/leaderboard | ❌ | ❌ | ✅ Unique | +| Streak / gamification | ❌ | ❌ | ✅ | +| Données envoyées serveur | ❌ | ❌ | ✅ (métriques agrégées) | +| Audit de sécurité | N/A | N/A | Fait (2026-03-04) | +| Maturité | ✅ Stable | ✅ Stable | ⚠️ Jeune | +| Open source | ✅ | ✅ | ⚠️ Code compilé only | + +--- + +## 📍 Recommandations + +### Action: Intégrer dans third-party-tools.md + +**Raisons**: +1. Angle unique (social tracking) non couvert ailleurs +2. Analyse de sécurité factuelle disponible — bonne occasion de documenter la bonne pratique d'inspecter un outil avant de le lancer +3. Le guide a déjà ccusage et ccburn ; Straude complète logiquement la section + +### Ce qui a été intégré + +- Entrée complète dans `guide/third-party-tools.md` (section Token & Cost Tracking) +- Description fonctionnelle, tableau des données transmises, notes de sécurité +- Recommandation `--dry-run` mise en avant + +### Éléments à surveiller (follow-up recommandé) + +- Publication d'une politique de confidentialité sur straude.com +- Maturité du projet (stars GitHub, adoption communautaire) +- Éventuels rapports d'incidents ou audits externes + +--- + +## 🔥 Challenge + +**Points de résistance potentiels**: + +1. "Un outil de 13 jours mérite-t-il une entrée dans le guide ?" + + Réponse : Oui, à condition de contextualiser clairement la maturité et les risques — ce qui est fait. Le guide documente déjà des outils récents (RTK). L'analyse de sécurité ajoute de la valeur indépendamment de l'outil lui-même. + +2. "L'envoi de données usage vers un tiers est-il acceptable ?" + + Réponse : C'est un choix utilisateur, pas une décision du guide. Notre rôle est d'informer clairement ce qui est transmis (fait), pas de décider à la place de l'utilisateur. + +3. "Le code source n'est pas open source, juste compilé lisible." + + Point valide. Noté comme limitation dans la fiche. Le TypeScript compilé sans minification reste lisible et auditable, ce qui est suffisant pour une analyse de surface. + +**Verdict challenge**: Score 3/5 maintenu. Intégration justifiée avec les guardrails documentés. + +--- + +## ✅ Fact-Check + +| Affirmation | Vérifiée | Source | +|-------------|----------|--------| +| Créé le 2026-02-18 | ✅ | `npm view straude time.created` | +| Version 0.1.9, 10 releases | ✅ | npm registry JSON | +| Maintenu par oscar.hong2015@gmail.com | ✅ | npm registry JSON | +| Token stocké en 0600 | ✅ | `dist/lib/auth.js` ligne `writeFileSync(..., { mode: 0o600 })` | +| Hostname envoyé | ✅ | `dist/commands/push.js` : `device_name: hostname()` | +| Données envoyées = métriques agrégées uniquement | ✅ | Corps du POST dans `push.js`, aucun accès fs autre que `~/.straude` | +| Pas de policy confidentialité | ✅ | straude.com inspecté 2026-03-04 | +| DEFAULT_API_URL = https://straude.com | ✅ | `dist/config.js` | + +--- + +## 🎯 Décision finale + +| Critère | Valeur | +|---------|--------| +| **Score final** | 3/5 | +| **Action** | ✅ Intégré (third-party-tools.md) | +| **Confiance** | Haute (code source inspecté directement) | + +**Résumé**: Outil unique pour le tracking social de consommation Claude Code. Analyse de sécurité rassurante sur les risques malveillants, réserves légitimes sur la maturité et l'absence de politique de confidentialité. Intégration avec guardrails clairs. + +--- + +## 📚 Références + +- Fiche dans le guide: `guide/third-party-tools.md` (section Token & Cost Tracking, après ccburn) +- Package npm: https://www.npmjs.com/package/straude +- Site: https://straude.com +- Code inspecté: `npm pack straude@0.1.9` → 20 fichiers, 35KB \ No newline at end of file diff --git a/examples/README.md b/examples/README.md index d2dbe23..3e34fe2 100644 --- a/examples/README.md +++ b/examples/README.md @@ -18,7 +18,7 @@ Annotated templates that teach you **why** patterns work, not just how to config | [`commands/`](./commands/) | Slash commands (workflow automation) | 26 | | [`hooks/`](./hooks/) | Event-driven security & automation scripts | 31 | | [`skills/`](./skills/) | Reusable knowledge modules — [9 on SkillHub](https://skills.palebluedot.live/owner/FlorianBruniaux) | 13 | -| [`claude-md/`](./claude-md/) | CLAUDE.md configuration profiles | 5 | +| [`claude-md/`](./claude-md/) | CLAUDE.md configuration profiles | 6 | | [`config/`](./config/) | Settings, MCP, git templates | 5 | | [`memory/`](./memory/) | CLAUDE.md memory file templates | 2 | | [`scripts/`](./scripts/) | Diagnostic & utility scripts | 13 | @@ -195,7 +195,7 @@ Security-first: 12 security hooks, 8 productivity hooks, 5 automation hooks, 5 m | [CLAUDE.md.project-template](./memory/CLAUDE.md.project-template) | Team project memory | | [CLAUDE.md.personal-template](./memory/CLAUDE.md.personal-template) | Personal global memory | -### CLAUDE.md Configurations (5) +### CLAUDE.md Configurations (6) | File | Purpose | |------|---------| @@ -204,6 +204,7 @@ Security-first: 12 security hooks, 8 productivity hooks, 5 automation hooks, 5 m | [product-designer.md](./claude-md/product-designer.md) | Product designer workflow configuration | | [tts-enabled.md](./claude-md/tts-enabled.md) | Text-to-speech enabled configuration | | [rtk-optimized.md](./claude-md/rtk-optimized.md) | RTK token-optimized configuration | +| [session-naming.md](./claude-md/session-naming.md) | Auto-rename sessions with descriptive titles for parallel work | > **See [guide/learning-with-ai.md](../guide/learning-with-ai.md) for learning mode documentation** > **See [guide/devops-sre.md](../guide/devops-sre.md) for DevOps/SRE guide** diff --git a/examples/claude-md/session-naming.md b/examples/claude-md/session-naming.md new file mode 100644 index 0000000..0952b90 --- /dev/null +++ b/examples/claude-md/session-naming.md @@ -0,0 +1,87 @@ +--- +title: "Session Auto-Rename" +description: "CLAUDE.md snippet to make Claude automatically name sessions with descriptive titles" +tags: [session, resume, productivity, workflow] +--- + +# Session Auto-Rename — CLAUDE.md Snippet + +Add this block to your global `~/.claude/CLAUDE.md` to make Claude automatically rename sessions with descriptive titles after 2-3 exchanges. Helps enormously when running parallel sessions (WebStorm, split terminals, multiple projects). + +## The Problem + +When running multiple Claude Code sessions in parallel, they all appear as "claude" or a truncated first prompt in session pickers. Finding the right session to `/resume` becomes guesswork. + +## The Solution + +A behavioral instruction in CLAUDE.md — no scripts, no hooks, no plugins. Claude understands the session subject early and calls `/rename` proactively. + +## Snippet + +```markdown +# Session Naming (auto-rename) + +## Expected behavior + +1. **Early rename**: Once the session's main subject is clear (after 2-3 exchanges), + run `/rename` with a short, descriptive title (max 50 chars) +2. **End-of-session update**: If scope shifted significantly from the initial rename, + propose a re-rename before closing + +## Title format + +`[action] [subject]` — examples: +- "fix whitepaper PDF build" +- "add auth middleware + tests" +- "refactor hook system" +- "research terminal tab rename" +- "update CC releases v2.2.0" + +## Rules + +- Max 50 characters +- No "Session:" prefix, no date +- Action verb first (fix, add, refactor, update, research, debug...) +- Multi-topic: use the dominant subject, not an exhaustive list +- Do NOT ask for confirmation on the early rename (just do it) +- Only propose confirmation for end-of-session re-rename if title changed +``` + +## Usage + +**Global** (all projects): Add to `~/.claude/CLAUDE.md` + +**Project-level**: Add to `.claude/CLAUDE.md` or `CLAUDE.md` in the project root + +## How it works + +This is a pure behavioral instruction — no tooling required. Claude: +1. Infers the session's main subject from the first 2-3 exchanges +2. Calls `/rename "fix auth middleware"` automatically (no confirmation prompt) +3. If the work pivots significantly, proposes a re-rename at end of session + +Named sessions appear in the `/resume` picker with their descriptive titles, making it easy to find and continue the right session. + +## Limitations + +- **Tab renaming**: Terminal tab names (WebStorm, iTerm2) are NOT renamed. JetBrains filters ANSI escape sequences used for tab title changes. The Claude session itself gets renamed, not the terminal tab. +- **Timing**: Claude renames after understanding the subject, not immediately on first message. + +## Verification + +```bash +# After a session with this configured: +claude --resume +# → Session list shows descriptive names like "fix auth middleware" +# instead of timestamps or truncated prompts +``` + +## Trade-offs + +| Approach | Pros | Cons | +|----------|------|------| +| This (behavioral instruction) | Zero tooling, works everywhere | Claude must infer timing | +| Manual `/rename` | Full control | Requires user action | +| Hook (Stop event) | Automatic | No access to conversation context | + +The behavioral instruction wins on simplicity and portability. diff --git a/guide/cowork.md b/guide/cowork.md index 84eb9f2..00dc57a 100644 --- a/guide/cowork.md +++ b/guide/cowork.md @@ -27,17 +27,30 @@ tags: [guide, agents, workflows] --- -## Quick Comparison +## Three Claude Tools: Which One for You? -| Aspect | Claude Code | Cowork | Projects | -|--------|-------------|--------|----------| -| **User** | Developers | Knowledge workers | Everyone | -| **Interface** | Terminal | Desktop app | Web chat | -| **Execute code** | Yes | No | No | -| **File access** | Full | Folder sandbox | Upload only | -| **Maturity** | Production | Research preview | Production | +Three tools, one subscription ($20/mo Pro). They're complementary, not competing. -→ [Full Comparison](https://github.com/FlorianBruniaux/claude-cowork-guide/blob/main/reference/comparison.md) +| | Claude AI | Claude Code | Cowork | +|---|-----------|-------------|--------| +| **Interface** | Web / Mobile | Terminal (CLI) | Desktop app | +| **Tagline** | You write, think, search | You code at scale | You automate without code | +| **Definition** | Generalist conversational assistant | Autonomous agent for full codebases | Agentic file workflows for non-devs | +| **Primary use cases** | Writing, brainstorming, research | Debugging, refactoring, testing | File organization, PDF extraction, cross-app workflows | +| **Executes code** | No | Yes | No | +| **File system access** | Upload only | Full | Folder sandbox | +| **Setup required** | None | npm install -g @anthropic-ai/claude-code | macOS app install | +| **Maturity** | Production | Production | Research preview | +| **Ideal profile** | Writer · Consultant · Student | Developer · Engineer · Tech Lead | Ops · Assistant · SMB non-tech | +| **Main tradeoff** | No system access | Token costs on heavy projects | macOS only, limited config | + +→ [Full Cowork vs Code comparison](https://github.com/FlorianBruniaux/claude-cowork-guide/blob/main/reference/comparison.md) + +### Decision guide + +- **Writing a doc or doing research?** → Claude AI +- **Coding: refactoring, debugging, tests?** → Claude Code (you're in the right place) +- **Organizing files, extracting PDFs, no code?** → Cowork --- diff --git a/guide/learning-with-ai.md b/guide/learning-with-ai.md index 8cad503..ebd873c 100644 --- a/guide/learning-with-ai.md +++ b/guide/learning-with-ai.md @@ -12,7 +12,7 @@ tags: [guide, workflows] > > **Reading time**: ~15 minutes > -> **Last updated**: January 2026 +> **Last updated**: March 2026 --- @@ -29,9 +29,10 @@ tags: [guide, workflows] 9. [Optimizing Your Flow (Pattern: Augmented)](#optimizing-your-flow) 10. [Case Study: Hybrid Learning Principles](#case-study-hybrid-learning-principles) 11. [30-Day Progression Plan](#30-day-progression-plan) -12. [Red Flags Checklist](#red-flags-checklist) -13. [Sources & Research](#sources--research) -14. [See Also](#see-also) +12. [For Tech Leads & Engineering Managers](#for-tech-leads--engineering-managers) +13. [Red Flags Checklist](#red-flags-checklist) +14. [Sources & Research](#sources--research) +15. [See Also](#see-also) --- @@ -150,6 +151,8 @@ The pattern: **AI excels at well-defined, repeatable tasks**. It struggles with The difference isn't the tool — it's the organizational discipline around it. +> **For team leads**: If you're responsible for structuring this — onboarding, policies, growth measurement — jump to [§12 For Tech Leads & Engineering Managers](#for-tech-leads--engineering-managers). + **On maintainability fear**: The concern that AI-generated code creates unmaintainable codebases is not empirically supported — downstream developers show no significant difference in evolution time or code quality (Borg et al., 2025, n=151). The real risks are skill atrophy and over-delegation, not inherent quality degradation for the next developer. ([arXiv:2507.00788](https://arxiv.org/abs/2507.00788)) ### Implications for Learning @@ -872,6 +875,137 @@ A concrete path from wherever you are to augmented developer. --- +## For Tech Leads & Engineering Managers + +> **Audience**: Engineering managers, tech leads, senior developers responsible for junior mentoring. +> +> **Problem**: The rest of this guide addresses individual developers. This section addresses the people responsible for creating the conditions where good habits form — or don't. + +The UVAL protocol solves the individual problem. The organizational problem is different: how do you create conditions where juniors *want to* think before they prompt, where quality isn't traded for velocity, and where AI-generated debt doesn't accumulate silently at team scale? + +--- + +### The Onboarding Imperative + +AI access without structured training produces poor results. A 2025 Create Future study found junior developers with no AI training achieved only 14-42% time savings on key tasks. With brief structured training, that jumped to 35-65%. The tool doesn't teach itself. + +**Structured onboarding beats "here's your license":** + +| Week | Focus | Avoid | +|------|-------|-------| +| 1 | Codebase tour without AI — baseline assessment | Granting Copilot access on day one | +| 2 | First features manually, AI as reviewer only | AI as generator before fundamentals are visible | +| 3 | UVAL protocol introduction + supervised pair sessions | Solo AI usage without check-ins | +| 4+ | Full AI usage with weekly understanding check-ins | Unmonitored velocity as success metric | + +Week 1 without AI isn't a punishment. It's calibration. You need to see what they actually know before AI masks the gaps. A junior who struggles week 1 needs different mentoring than one who ships confidently — and you can't distinguish them if they both use AI from day one. + +--- + +### Measuring What Actually Matters + +Velocity is a lagging indicator. It shows nothing about the skills gap forming underneath. + +**Metrics that reveal real growth:** + +| Metric | How to Measure | Red Flag | +|--------|---------------|----------| +| Can explain code in review | Ask "walk me through your approach" | "The AI suggested it" | +| Debugs independently | Time to resolve self-reported blockers | Always needs AI to debug | +| Predicts outcomes | Ask "what will this do?" before running | Can't answer without testing | +| Proposes alternatives | In design discussions | Always defers to AI output | +| Notices when AI is wrong | Review comment quality | Never catches AI errors | + +**Weekly growth question** (5 minutes, any format): + +> "What's one thing you understood deeply this week — not just shipped?" + +If they struggle to answer two weeks in a row, that's your signal to slow down. + +--- + +### Scalable Mentoring Models + +The 1:1 senior/junior compagnonnage model doesn't scale past teams of 5-10. These three approaches do: + +**1. Pair programming rotations (2-hour slots)** + +Two juniors work together with AI. The constraint: neither can accept AI code they can't explain to their partner. Disagreements on the *why* are escalated to a senior. Cost: 2h/week per junior, minimal senior time. + +**2. Architecture "hot seat" (15 min/week)** + +Any junior can request a 15-minute slot to explain an architectural decision they made. Senior gives one piece of feedback. No code review — just the *why* behind the choice. Scales to N juniors with O(N×15min) senior time, and forces juniors to develop architectural reasoning rather than just copy AI solutions. + +**3. Collective CLAUDE.md ownership** + +Juniors propose additions to the team `CLAUDE.md`. Proposals must be based on something that burned them or saved them in practice. Seniors review and accept or reject with a reason. This forces reflection, distributes knowledge horizontally, and builds shared ownership of the team's AI usage standards. + +--- + +### Team-Level AI Policy (CLAUDE.md for Teams) + +Individual `CLAUDE.md` configuration (§6) is for one developer. Team-level policy goes in the root `CLAUDE.md` of your shared repo. Keep it short enough that people actually read it: + +```markdown +## Team AI Usage Policy + +### Required before using AI on a feature +- Write the function signature yourself +- Write at least one test case before asking AI to implement + +### Required after AI generates code +- All AI-generated code undergoes the same code review as human code +- Reviewer asks: "Can you explain this section?" for junior PRs — not optional + +### Prohibited patterns +- Accepting AI changes without reading the diff +- AI-generated code in security-critical paths without explicit senior sign-off +- Using "AI wrote it" as explanation for any architectural decision in a PR +``` + +Start minimal. Add rules only when a pattern becomes a problem. A six-page policy nobody reads is worse than a three-rule policy that shapes behavior. + +--- + +### Warning Signs at Team Level + +| Pattern | What It Means | Response | +|---------|---------------|----------| +| PRs merged faster each week, quality dropping | Probably skipping review | Add mandatory "explain this" checklist for junior PRs | +| Juniors never ask architectural questions | Over-delegating thinking to AI | Architecture hot seat (see above) | +| Bugs consistently blamed on "AI-generated code" | No code ownership | Review acceptance policy — who's responsible for what they ship? | +| Senior devs increasingly vocal about code quality | Debt accumulating silently | Slow down — introduce "explain this" gates before merge | +| Same fundamental question asked every sprint | Not retaining, just re-prompting | Require learning log, review at 1:1s | +| Junior velocity rises but interview performance falls | The Shen & Tamkin effect at team scale | Reset with week of no-AI exercises on known fundamentals | + +--- + +### Quick Checklist + +``` +Onboarding +☐ Week 1: no AI, baseline skills visible before tooling provided +☐ Structured AI training included (not just tool access) +☐ UVAL protocol introduced by week 3 + +Ongoing +☐ Code reviews include "explain this" for junior PRs +☐ Weekly growth question asked (not just velocity reviewed) +☐ Architecture hot seat or equivalent ritual active + +Team Policy +☐ CLAUDE.md with AI usage guidelines exists in repo +☐ Prohibited patterns documented and known +☐ Someone owns updating the policy as patterns evolve + +Warning Signs +☐ Velocity tracked separately from understanding signals +☐ Debt accumulation monitored (not just feature throughput) +☐ Juniors can explain code they shipped last sprint +``` + +--- + ## Red Flags Checklist Warning signs you're becoming dependent, and what to do: @@ -928,6 +1062,13 @@ Sources for [§3 The Reality of AI Productivity](#the-reality-of-ai-productivity - **Borg et al. "Echoes of AI" RCT (2025)** — [arXiv:2507.00788](https://arxiv.org/abs/2507.00788) — 2-phase blind RCT (151 participants, 95% professional developers): AI users 30.7% faster (median), habitual users ~55.9% faster. Phase 2: downstream developers evolving AI-generated code showed no significant difference in evolution time or code quality vs. human-generated code. First RCT to explicitly target maintainability of AI-assisted code. Co-authored by Dave Farley ("Continuous Delivery"). Note: arXiv preprint (v2 Dec 2025), not yet published in peer-reviewed proceedings. - **DORA/Google DevOps Research (2024)** — AI tool adoption impact on team performance +### Team & Organizational Research + +- **Create Future: AI Training Impact on Junior Developers (2025)** — Structured AI training raises junior time savings from 14-42% (untrained) to 35-65% (trained) on key tasks. Source for [§12 Onboarding Imperative](#the-onboarding-imperative). +- **Stanford Digital Economy Study (2025)** — Software developer employment for ages 22-25 declined ~20% by July 2025. Context for the urgency of structured junior development. [understandingai.org analysis](https://www.understandingai.org/p/new-evidence-strongly-suggest-ai) +- **LeadDev: Tech CEOs reckon with AI impact on junior developers (2025)** — [leaddev.com](https://leaddev.com/leadership/tech-ceos-reckon-with-impact-junior-developers) — Organizational perspectives from engineering leaders on structuring junior growth in AI-heavy teams. +- **Stack Overflow: AI vs Gen Z (2025)** — [stackoverflow.blog](https://stackoverflow.blog/2025/12/26/ai-vs-gen-z/) — Career pathway shifts for junior developers with AI adoption data by experience level. + ### Practitioner Perspectives - **Anthropic Claude Code Best Practices** — [anthropic.com](https://www.anthropic.com/engineering/claude-code-best-practices) — Official guidance on effective usage diff --git a/guide/third-party-tools.md b/guide/third-party-tools.md index 338fba9..573f31a 100644 --- a/guide/third-party-tools.md +++ b/guide/third-party-tools.md @@ -89,6 +89,49 @@ A Python TUI for visual token burn-rate tracking. Displays charts showing consum --- +### Straude + +A social dashboard for tracking and sharing Claude Code (and OpenAI Codex) usage stats. Push your daily token consumption and costs to a public leaderboard to track your streak, weekly spend, and global rank. + +| Attribute | Details | +|-----------|---------| +| **Source** | [npm: straude](https://www.npmjs.com/package/straude) | +| **Website** | [straude.com](https://straude.com) | +| **Install** | `npx straude@latest` | +| **Language** | TypeScript (Node.js 18+) | +| **Version** | 0.1.9 (active development, created Feb 2026) | +| **Maintainer** | Community (oscar.hong2015@gmail.com) | + +**Key features**: + +- `straude` — smart sync: authenticate + push usage in one command +- `straude push --dry-run` — preview what would be submitted without sending +- `straude push --days N` — backfill last N days (max 7) +- `straude status` — streak, weekly spend, token totals, global rank +- Tracks both Claude Code (`ccusage`) and OpenAI Codex (`@ccusage/codex`) + +**What is sent to the Straude server**: + +Per day: cost in USD, token counts (input/output/cache creation/cache read), model names used (e.g. `claude-sonnet-4-6`), per-model cost breakdown. Plus: a SHA256 hash of the raw data, a random device UUID, and your machine hostname. + +Your source code, API keys, and conversation content are **not** accessed or transmitted. + +**Security notes**: + +- Auth token stored in `~/.straude/config.json` with `0600` permissions (owner-only) +- Project is very young (created 2026-02-18, rapid iteration) — no public security audit +- Machine hostname is sent as `device_name` +- No published privacy policy as of March 2026 +- Use `--dry-run` to verify what would be submitted before your first push + +**When to choose Straude over ccusage/ccburn**: + +Straude is the only tool in this list that is **social** — it uploads your stats to a shared platform. If you want a leaderboard, streak tracking, or to benchmark your usage against other developers, Straude is unique. If you want local-only cost visibility, ccusage or ccburn are better fits and carry no data-sharing implications. + +> **Security reminder**: Before running any community CLI tool with `npx`, review its npm page and source for red flags. For Straude, the compiled source is readable and consistent with its stated purpose. See the [resource evaluation](../docs/resource-evaluations/straude-evaluation.md) for the full analysis. + +--- + ### RTK (Rust Token Killer) A CLI proxy that filters command outputs **before** they reach Claude's context. 446 stars, 38 forks, 700+ upvotes on r/ClaudeAI. diff --git a/machine-readable/reference.yaml b/machine-readable/reference.yaml index 09eb702..915f1ae 100644 --- a/machine-readable/reference.yaml +++ b/machine-readable/reference.yaml @@ -166,6 +166,8 @@ deep_dive: productivity_rct_echoes: "guide/learning-with-ai.md:926" # Borg 2025: 30.7% faster (median), ~55.9% habitual users, no maintainability impact downstream productivity_maintainability_empirical: "guide/learning-with-ai.md:926" # Empirical data on "AI code is unmaintainable" claim — blind RCT shows no significant difference trust_calibration_maintainability_nuance: "guide/ultimate-guide.md:1097" # Nuance: defect rates ≠ maintenance burden (Borg et al. 2025) + session_naming_template: "examples/claude-md/session-naming.md" + session_naming_guide: "guide/ultimate-guide.md:815" learning_mode_template: "examples/claude-md/learning-mode.md" learn_quiz_command: "examples/commands/learn/quiz.md" learn_teach_command: "examples/commands/learn/teach.md" @@ -259,6 +261,10 @@ deep_dive: third_party_ccusage: "https://www.npmjs.com/package/ccusage" third_party_ccusage_site: "https://ccusage.com" third_party_ccburn: "https://github.com/JuanjoFuchs/ccburn" + third_party_straude: "https://straude.com" + third_party_straude_npm: "https://www.npmjs.com/package/straude" + third_party_straude_guide: "guide/third-party-tools.md:92" + third_party_straude_eval: "docs/resource-evaluations/straude-evaluation.md" third_party_claude_code_viewer: "https://www.npmjs.com/package/@kimuson/claude-code-viewer" third_party_claude_code_config: "https://github.com/joeyism/claude-code-config" third_party_aiblueprint: "https://github.com/Melvynx/aiblueprint"