diff --git a/CHANGELOG.md b/CHANGELOG.md index 56e1f54..842960d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,37 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ## [Unreleased] +### Added + +- **Resource evaluation**: SKILLMIND/Boris Cherny workflow practices (score 2/5) + - LinkedIn post by @stasbel (64K followers) sharing SKILL.md file attributed to Boris Cherny (Claude Code creator) + - 6 workflow orchestration practices + 6 task management items + 3 core principles + - Key concept: `tasks/lessons.md` self-improvement loop (Claude captures corrections as rules, reviewed each session) + - Score 2/5: majority of content already covered in guide; novel delta = lessons.md naming convention vs PROGRESS.md + - Evaluation file: `docs/resource-evaluations/2026-02-19-stasbel-skillmind-boris-cherny-workflow.md` + +- **Resource evaluation**: Augment Context Engine MCP (score 3/5) + - Cloud-hosted semantic code search MCP (launched Feb 6, 2026); indexes up to 500K files across repos/wikis + - Self-published benchmark: 80% quality improvement on 300 Elasticsearch PRs (Claude Opus 4.5, not 4.6 as stated on product page) + - Relevant as cloud alternative to grepai: managed, multi-repo, no local setup, but paid ($20+/month) and cloud-hosted + - Evaluation file: `docs/resource-evaluations/2026-02-19-augment-context-engine-mcp.md` + +- **Resource evaluation**: LinkedIn "Context Engineering" post (score 2/5) + - Promotional LinkedIn post on "prompt engineering is dead, context engineering is king" — marginal relevance + - Evaluation file: `docs/resource-evaluations/2026-02-19-linkedin-context-engineering-augment.md` + +- **Resource evaluation**: LinkedIn activity-7428930570451083264 (inaccessible) + - Could not fetch — LinkedIn authentication required + - Evaluation file: `docs/resource-evaluations/2026-02-19-linkedin-activity-7428930570451083264.md` + +### Changed + +- `guide/ultimate-guide.md`: Added `tasks/lessons.md` variant to Fresh Context Pattern (Ralph Loop) section + - Lightweight alternative for interactive sessions: Claude updates lessons.md with behavioral rules after each user correction + - Reviewed at session start for compounding improvement effect + - Clarifies distinction from PROGRESS.md (task state) vs lessons.md (behavioral rules) +- `CLAUDE.md`: Added Whitepaper Generation section (PDF + EPUB commands, stack documentation) + ### Documentation - **Claude Code Releases**: Updated tracking to v2.1.47 (from v2.1.45) diff --git a/CLAUDE.md b/CLAUDE.md index 91aa6fa..e388fec 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -70,6 +70,43 @@ claudedocs/ # Claude working documents (gitignored) echo "3.7.0" > VERSION && ./scripts/sync-version.sh ``` +### Whitepaper Generation (PDF + EPUB) + +```bash +# --- PDF (default format: whitepaper-typst → Typst → PDF) --- + +# Single file +cd whitepapers/fr && quarto render 00-introduction-serie.qmd + +# All FR whitepapers +cd whitepapers/fr && quarto render *.qmd + +# All EN whitepapers +cd whitepapers/en && quarto render *.qmd + +# Preview with hot-reload +cd whitepapers/fr && quarto preview 00-introduction-serie.qmd + +# Batch with error summary (loop) +cd whitepapers/fr && for f in *.qmd; do echo "→ $f" && quarto render "$f" 2>&1 | grep -E "(Output created|ERROR)"; done + +# --- EPUB (format: epub → Pandoc → EPUB3) --- + +# Single file +cd whitepapers/fr && quarto render 00-introduction-serie.qmd --to epub + +# All EPUBs (FR + EN) → epub-output/{fr,en}/ +cd whitepapers && ./render-epub.sh all +cd whitepapers && ./render-epub.sh fr # French only +cd whitepapers && ./render-epub.sh en # English only +``` + +**PDF stack** : Quarto → Typst 0.13 → PDF. Template : `whitepapers/_extensions/whitepaper/`. Palette Bold Guy (warm beige + orange brûlé). + +**EPUB stack** : Quarto → Pandoc → EPUB3. CSS : `whitepapers/epub-styles.css`. Cover : `_extensions/whitepaper/assets/claude-code-ai-logo.jpg`. + +**Skill disponible** : `/pdf-generator` pour aide contextuelle (template YAML, stack, dépannage). + ### Before Committing ```bash # Verify versions are synchronized diff --git a/README.md b/README.md index 283fee9..2157d7c 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ Last Update Quiz Templates - Threat Database + Threat Database

@@ -140,7 +140,7 @@ graph LR root --> quiz[🧠 quiz/
274 questions] root --> tools[🔧 tools/
utils] root --> machine[🤖 machine-readable/
AI index] - root --> docs[📚 docs/
67 evaluations] + root --> docs[📚 docs/
78 evaluations] style root fill:#d35400,stroke:#e67e22,stroke-width:3px,color:#fff style guide fill:#2980b9,stroke:#3498db,stroke-width:2px,color:#fff @@ -186,7 +186,7 @@ graph LR │ ├─ reference.yaml Structured index (~2K tokens) │ └─ llms.txt Standard LLM context file │ -└─ 📚 docs/ 67 Resource Evaluations +└─ 📚 docs/ 78 Resource Evaluations └─ resource-evaluations/ 5-point scoring, source attribution ``` @@ -283,7 +283,7 @@ Educational templates with explanations: --- -### 🔍 67 Resource Evaluations +### 🔍 78 Resource Evaluations **Outcome**: Trust our recommendations are evidence-based. @@ -695,7 +695,7 @@ cd quiz && npm install && npm start

-Resource Evaluations (67 assessments) +Resource Evaluations (78 assessments) Systematic evaluation of external resources (tools, methodologies, articles) before integration into the guide. diff --git a/docs/resource-evaluations/2026-02-19-augment-context-engine-mcp.md b/docs/resource-evaluations/2026-02-19-augment-context-engine-mcp.md new file mode 100644 index 0000000..ab9dd98 --- /dev/null +++ b/docs/resource-evaluations/2026-02-19-augment-context-engine-mcp.md @@ -0,0 +1,162 @@ +# Evaluation: Augment Code - Context Engine MCP + +**Date**: 2026-02-19 +**Evaluator**: Claude Sonnet 4.6 +**Source Type**: Product page (commercial tool) +**URL**: https://www.augmentcode.com/product/context-engine-mcp +**Verdict**: RELEVANT (Score: 3/5) + +--- + +## Content Summary + +Augment Code launched its Context Engine as a standalone MCP server on February 6, 2026. It provides semantic code search for any MCP-compatible coding agent (Claude Code, Cursor, Zed, Kilo Code, Roo Code, GitHub Copilot). + +**Key points**: + +1. **What it does**: Cloud-hosted semantic search MCP that indexes codebases (across repos, docs, wikis) and provides context to AI agents via MCP protocol. Indexes up to 400,000-500,000 files using semantic dependency graphs. + +2. **Benchmark claims**: Tested on 300 Elasticsearch pull requests (900 attempts with 3 prompts each). Results: + - Claude Code + Opus 4.5: +80% quality improvement + - Cursor + Opus 4.5: +71% improvement (completeness +60%, correctness +5x) + - Cursor + Composer-1: +30% improvement + +3. **Efficiency**: Requires fewer tool calls and conversation turns; reduces token usage vs baseline without context engine. + +4. **Architecture**: Cloud-hosted (not local), real-time indexing, multi-source connectors (GitHub, GitLab, Bitbucket). + +5. **Pricing**: Credit-based ($20/month Indie = 40,000 credits, $50/month Developer = 600 messages). 1,000 free requests during launch period (through Feb 2026, now expired). + +--- + +## Fact-Check Results + +| Claim | Source | Verdict | +|-------|--------|---------| +| **"+80% quality improvement" (Claude Code + Opus 4.5)** | Augment blog, confirmed by Perplexity search | ✅ CONFIRMED — but note: published by Augment themselves, no independent replication | +| **"300 Elasticsearch PRs, 900 attempts"** | Augment blog | ✅ PLAUSIBLE — methodology is at least described, unlike many competitor claims | +| **"2x faster task completion"** | Product page only | ⚠️ UNVERIFIED — not backed by the benchmark data cited; appears in marketing copy only | +| **"Works with Claude Code, Cursor, Zed..."** | Product page, confirmed | ✅ CONFIRMED — standard MCP compatibility | +| **"400,000-500,000 file indexing"** | Augment comparison page | ✅ CONFIRMED via Perplexity | +| **Model cited: "Claude Opus 4.6"** | Product page | ⚠️ DISCREPANCY — Perplexity sources + Augment blog consistently say "Claude Opus 4.5". The product page appears to have been updated after the original benchmark. The underlying benchmark used Opus 4.5. | + +### Factual Corrections + +**Model version discrepancy**: The product page references "Claude Opus 4.6" but the original benchmark blog post (Feb 6, 2026) and all secondary sources reference "Claude Opus 4.5". The product page was likely updated to reflect the current model after the benchmark was run. This is a minor but notable inconsistency — the 80% figure comes from Opus 4.5 testing. + +**"2x faster" claim**: This specific number appears in marketing copy on the product page but is not directly backed by the Elasticsearch benchmark data. The benchmark measures quality dimensions (correctness, completeness, best practices, code reuse, documentation) — not task completion speed. Treat as unverified. + +--- + +## Gap Analysis: What the Guide Already Covers + +The guide has strong coverage of the semantic code search MCP space: + +| Aspect | Guide Coverage | Augment Context Engine | +|--------|---------------|----------------------| +| **Semantic search MCP** | grepai (fully documented, Section: Code Search & Analysis) | Same use case, cloud-hosted | +| **Local vs cloud tradeoff** | grepai = local/private documented explicitly | Augment = cloud-hosted, no local option | +| **Call graph analysis** | grepai: callers/callees/graph tools | Not mentioned in Augment product | +| **Setup & config** | Full install guide for grepai | Install via MCP config | +| **Token efficiency** | grepai: ~4K tokens vs 15K brute force | Augment: "fewer tool calls" (unquantified) | +| **Benchmark data** | None for grepai | 300 PRs, 3 dimensions, specific % gains | +| **Multi-repo support** | Not in grepai | Yes — GitHub, GitLab, Bitbucket connectors | +| **Pricing/cost** | grepai = free, local | Augment = $20+/month subscription | +| **Privacy** | grepai = fully local ("no data leaves your machine") | Augment = cloud-hosted, data sent to Augment | + +**Gap identified**: The guide's Code Search & Analysis section documents only grepai (1 server). The section introduction does not discuss the cloud vs local tradeoff for semantic search MCPs, nor does it acknowledge commercial/cloud alternatives like Augment. Users who want a managed, multi-repo solution with proven benchmark results have no guidance. + +**Secondary gap**: Augment's benchmark is the most concrete published data comparing semantic context provision to AI coding agents. The guide cites no equivalent quality-improvement benchmarks for grepai. + +--- + +## Scoring + +### Score: **3/5** (Relevant - useful complement) + +| Criterion | Score | Justification | +|-----------|-------|---------------| +| **Source Credibility** | 3/5 | Commercial product page. Benchmark methodology is described (300 PRs) but self-published. No independent replication. | +| **Factual Accuracy** | 3/5 | Core benchmark claim confirmed via Perplexity. Minor model version discrepancy. "2x faster" claim unverified. | +| **Timeliness** | 5/5 | GA launched Feb 6, 2026 — evaluated Feb 19, 2026. Current. | +| **Practical Value** | 3/5 | Fills a real gap: cloud/managed semantic search MCP for users who don't want local Ollama setup | +| **Novelty** | 3/5 | Same category as grepai (already in guide), but different deployment model + benchmark data is genuinely new | +| **Completeness** | 3/5 | Benchmark methodology described, but quality metrics aren't reproduced publicly; pricing requires separate page | + +**Weighted Average**: (3+3+5+3+3+3)/6 = **3.3/5** → rounded to **3/5** + +--- + +## Comparative Analysis: Augment vs Grepai vs Guide's Current Coverage + +| Dimension | Grepai (in guide) | Augment Context Engine | Winner for guide | +|-----------|-------------------|----------------------|-----------------| +| **Privacy** | Local only, zero cloud | Cloud-hosted | Grepai for privacy-conscious users | +| **Setup friction** | High (Ollama + nomic-embed-text + grepai init) | Low (MCP config + account signup) | Augment for ease | +| **Multi-repo** | Single project at a time | Cross-repo, cross-wiki | Augment for large orgs | +| **Cost** | Free | $20+/month | Grepai | +| **Call graph** | Full (callers/callees/graph) | Not documented | Grepai | +| **Benchmark evidence** | None published | 80% quality improvement (self-published) | Augment | +| **Independence** | Open source (MIT) | Proprietary, vendor lock-in | Grepai | + +**Key finding**: These are genuinely different tools serving different users. Grepai = privacy-first, free, local, with call graphs. Augment = managed, paid, cloud, multi-repo, with benchmark data. The guide currently presents grepai as the only option in this category — that's an incomplete picture. + +--- + +## Integration Recommendation + +Score 3/5 — integrate as a documented alternative. + +**Recommended action**: Add Augment Context Engine MCP as a secondary entry in the `mcp-servers-ecosystem.md` Code Search & Analysis section, positioned explicitly as "the cloud/managed alternative to grepai." + +**What to include**: +1. Brief description of the tool and its differentiation (cloud, multi-repo, managed) +2. Reference to the Elasticsearch benchmark (with caveat: self-published, Opus 4.5) +3. Privacy warning: data sent to Augment cloud +4. Pricing note: credit-based subscription required +5. Link: https://www.augmentcode.com/product/context-engine-mcp + +**What to explicitly NOT do**: +- Do not present the 80% or "2x faster" marketing numbers as facts without caveat +- Do not displace grepai as the primary recommendation (grepai remains better for privacy, cost, and call graph analysis) +- Do not expand this to a full section — it's an alternative mention, not a primary recommendation + +**Suggested placement** in `mcp-servers-ecosystem.md` after the existing grepai section: + +```markdown +#### Augment Context Engine MCP + +**Commercial alternative** for users who prefer a managed cloud service over local Ollama setup. +Indexes across multiple repos, wikis, and documentation sources via GitHub/GitLab/Bitbucket connectors. + +**Trade-offs vs grepai**: +- Pro: No local setup, multi-repo support, managed indexing +- Con: Cloud-hosted (data leaves your machine), paid subscription ($20+/month), no call graph analysis + +**Benchmark**: Augment reports 80% quality improvement on a 300-PR Elasticsearch test dataset +(self-published benchmark, Claude Opus 4.5, Feb 2026). + +**Setup**: https://app.augmentcode.com/mcp/configuration +**Docs**: https://www.augmentcode.com/product/context-engine-mcp +``` + +--- + +## Final Decision + +- **Score**: **3/5** (Relevant - integrate as secondary alternative) +- **Action**: APPROVED for minimal integration in `mcp-servers-ecosystem.md` +- **Confidence**: High +- **Priority**: Low — not urgent, but useful to prevent the impression that grepai is the only option + +### Why NOT a higher score? + +- Not a new concept: same category as grepai, already well-covered +- Self-published benchmarks without independent replication +- Cloud-only = non-starter for any privacy-sensitive environment +- The guide's primary audience (developers using Claude Code CLI) likely prefers local/free tools over managed subscriptions + +--- + +**Evaluation completed**: 2026-02-19 +**Result**: Score 3/5. Useful complement to document as a cloud alternative to grepai. Integrate with clear privacy/cost caveats, no displacement of primary grepai recommendation. diff --git a/docs/resource-evaluations/2026-02-19-linkedin-activity-7428930570451083264.md b/docs/resource-evaluations/2026-02-19-linkedin-activity-7428930570451083264.md new file mode 100644 index 0000000..e7ac89c --- /dev/null +++ b/docs/resource-evaluations/2026-02-19-linkedin-activity-7428930570451083264.md @@ -0,0 +1,39 @@ +# Evaluation: LinkedIn Post - activity-7428930570451083264 + +**Date**: 2026-02-19 +**Evaluator**: Claude Sonnet 4.6 +**Source Type**: LinkedIn post (unknown author, unknown content) +**Verdict**: INACCESSIBLE - Cannot evaluate + +--- + +## Fetch Result + +WebFetch returned LinkedIn's sign-up/login page. The post is behind an authentication wall. No content was retrievable. + +**URL**: https://www.linkedin.com/posts/activity-7428930570451083264-I3Pa + +**What can be inferred from the URL structure**: +- `activity-7428930570451083264` is a standard LinkedIn activity post ID +- Author reference: `ACoAABGhhKgBLYdSS8KjqEyTSCUE4m21LrNR0_I` (an anonymized LinkedIn member ID) +- No title, no topic, no engagement data visible from metadata +- URL contains no slug or topic hint + +--- + +## Scoring: N/A + +Cannot assign a score to inaccessible content. Evaluating based on unknown content would be fabrication. + +--- + +## Decision + +**Score**: N/A (unscored) +**Action**: NOT EVALUATED - Content inaccessible +**Recommendation**: Requester should provide the post content directly (copy-paste) or identify the author for targeted follow-up search. + +--- + +**Evaluation completed**: 2026-02-19 +**Result**: Inaccessible. LinkedIn requires authentication. No evaluation possible without content. diff --git a/docs/resource-evaluations/2026-02-19-linkedin-context-engineering-augment.md b/docs/resource-evaluations/2026-02-19-linkedin-context-engineering-augment.md new file mode 100644 index 0000000..331a357 --- /dev/null +++ b/docs/resource-evaluations/2026-02-19-linkedin-context-engineering-augment.md @@ -0,0 +1,97 @@ +# Evaluation: LinkedIn Post — "Prompt Engineering is dead. Context Engineering is king." + +**Date**: 2026-02-19 +**Evaluator**: Claude Sonnet 4.6 +**Source Type**: LinkedIn post (promotional, personal testimonial) +**URL**: https://www.linkedin.com/posts/activity-7428930570451083264-I3Pa +**Author**: Unknown (LinkedIn member, anonymous for evaluation purposes) +**Verdict**: MARGINAL (Score: 2/5) + +--- + +## Content Summary + +LinkedIn post using the "Context Engineering" framing to promote Augment Code's Context Engine MCP server. + +**Key points**: + +1. **Main thesis**: "Prompt Engineering is dead. Context Engineering is king." — Positions context quality as the #1 leverage point for AI coding agents, above model choice or prompts. + +2. **Product promotion**: Recommends installing Augment Code's Context Engine MCP (already evaluated separately as Resource 2, score 3/5). Uses knowledge graph + semantic indexing to provide better context. + +3. **Personal testimonial**: Author claims to have tested on a 30,000-line ML pipeline codebase: "After indexing with Context Engine, I can answer questions twice as fast as before." + +4. **Practical tip**: Suggests updating CLAUDE.md to always use this MCP server to index and answer questions about the repository. + +5. **Links**: Redirects to Augment's MCP configuration page (via shortened URLs fandf.co/3ZgA4V7 and fandf.co/4r1Hdoq). + +--- + +## Fact-Check Results + +| Claim | Source | Verdict | +|-------|--------|---------| +| **"Context Engineering" is a legitimate concept** | Andrej Karpathy (June 2025), Shopify CEO Tobi Lütke, LangChain, Anthropic blog | ✅ CONFIRMED — coined/popularized June 2025, well-established | +| **"LLM is CPU, context window is RAM" framing** | Karpathy's original definition | ✅ CONFIRMED — accurate attribution (though post doesn't cite him) | +| **"2x speed" from personal 30k line ML codebase** | Author's own experience | ⚠️ UNVERIFIABLE — single anonymous testimonial, not reproducible | +| **"Lower token usage"** | Partially supported by Augment's product page ("fewer tool calls") | ⚠️ UNQUANTIFIED — no benchmark backing | +| **Knowledge graph + semantic indexing** | Augment product page | ✅ CONFIRMED — accurate product description | +| **"Same Opus 4.5 model... different contexts = 2x speed"** | Personal claim | ⚠️ UNVERIFIED — consistent with Augment's unverified marketing copy | + +**Model note**: Post correctly references "Opus 4.5" — consistent with Augment's actual benchmark (unlike their product page which was updated to "Opus 4.6"). + +--- + +## Gap Analysis: Guide Coverage + +| Topic | Guide Coverage | LinkedIn Post | +|-------|---------------|---------------| +| **"Context Engineering" concept** | ✅ Well-covered — `guide/methodologies.md` (dedicated section + 4 references), `guide/ultimate-guide.md` (multiple mentions including Anthropic blog link) | Same concept, less precise | +| **Karpathy "LLM = CPU, context = RAM" metaphor** | ✅ Referenced in `guide/ultimate-guide.md:12356` ("Software engineering might be more workflow + context engineering") | Implicit, not attributed | +| **Augment Context Engine MCP** | ⚠️ Not yet documented — see separate eval 2026-02-19-augment-context-engine-mcp.md | Primary topic of post | +| **CLAUDE.md tip: instruct to use MCP for indexing** | ❌ Not documented as a pattern | Single sentence practical tip | +| **Context > model quality claim** | ✅ Covered in guide (context management is described as "the most important concept") | Reinforce with marketing framing | + +**Key finding**: The guide already has superior coverage of "Context Engineering" as a concept — citing Anthropic's official blog, ArXiv papers, and multiple frameworks. The LinkedIn post adds no theoretical depth. The only marginally new element is the CLAUDE.md tip about always using an MCP server for repository indexing. + +--- + +## Scoring + +### Score: **2/5** (Marginal) + +| Criterion | Score | Justification | +|-----------|-------|---------------| +| **Source Credibility** | 1/5 | Anonymous LinkedIn user, promotional intent, no credentials cited | +| **Factual Accuracy** | 3/5 | Core "Context Engineering" concept accurate; "2x" claim unverified personal testimonial | +| **Timeliness** | 4/5 | Recent post, current product | +| **Practical Value** | 2/5 | One minor CLAUDE.md tip; rest is product promotion already evaluated elsewhere | +| **Novelty** | 1/5 | Concept already well-covered; product already evaluated as Resource 2 | +| **Completeness** | 2/5 | Thin coverage, no technical depth, links to external pages | + +**Weighted Average**: (1+3+4+2+1+2)/6 = **2.2/5** → **2/5** + +--- + +## Decision + +### Score: **2/5** — NOT recommended for integration + +**Reasons**: +1. "Context Engineering" concept already documented better in the guide (Anthropic blog, ArXiv, methodologies section) +2. The promoted product (Augment Context Engine MCP) is handled by the separate evaluation (score 3/5) with much better factual coverage +3. Anonymous personal testimonial ("2x speed on 30k ML pipeline") is not verifiable — adding it to the guide would lower credibility +4. The only unique practical value — "Update CLAUDE.md to always use MCP for indexing" — is a single sentence that could optionally be added to the Augment integration note + +**One extractable element** (optional): +If/when Augment Context Engine is integrated (per Resource 2 recommendation), add a CLAUDE.md instruction pattern: +```markdown +> **CLAUDE.md tip**: Add an instruction to always use the Context Engine MCP for +> repository questions: "Use augment_search for any question about the codebase structure." +``` +This is a minor practical addition, not justifying full integration of this post. + +--- + +**Evaluation completed**: 2026-02-19 +**Result**: Score 2/5. Post is promotional content for a product already evaluated. The "Context Engineering" framing is better documented elsewhere in the guide. No integration recommended beyond the optional CLAUDE.md tip if Augment is added. diff --git a/docs/resource-evaluations/2026-02-19-stasbel-skillmind-boris-cherny-workflow.md b/docs/resource-evaluations/2026-02-19-stasbel-skillmind-boris-cherny-workflow.md new file mode 100644 index 0000000..3f82d15 --- /dev/null +++ b/docs/resource-evaluations/2026-02-19-stasbel-skillmind-boris-cherny-workflow.md @@ -0,0 +1,124 @@ +# Evaluation: SKILL.md / SKILLMIND — Boris Cherny Workflow Practices + +**Date:** 2026-02-19 +**Evaluator:** Claude (Sonnet 4.6) +**Status:** Mention uniquement (voir conclusion) + +**Sources:** +- LinkedIn: [Stanislav Beliaev — "This SKILL.md file will make you 10x engineer"](https://www.linkedin.com/posts/stasbel_this-%F0%9D%97%A6%F0%9D%97%9E%F0%9D%97%9C%F0%9D%97%9F%F0%9D%97%9F%F0%9D%97%BA%F0%9D%97%B1-file-will-make-you-10x-activity-7430215933832425472-MDvA) +- X/Twitter: [bcherny/status/2017742741636321619](https://x.com/bcherny/status/2017742741636321619) (non fetchable — JS requis) + +--- + +## 📄 Résumé du contenu + +- **Format**: Fichier SKILL.md (ou CLAUDE.md-style) contenant des workflow practices attribuées à Boris Cherny (créateur Claude Code @ Anthropic) +- **Workflow Orchestration (6 practices)**: Plan Node Default, Subagent Strategy, Self-Improvement Loop, Verification Before Done, Demand Elegance (Balanced), Autonomous Bug Fixing +- **Task Management (6 items)**: Plan First (`tasks/todo.md`), Verify Plan, Track Progress, Explain Changes, Document Results, Capture Lessons (`tasks/lessons.md`) +- **Core Principles (3)**: Simplicity First, No Laziness, Minimal Impact +- **Concept clé unique**: Self-Improvement Loop — après TOUTE correction utilisateur → mettre à jour `tasks/lessons.md` avec des règles, review au début de session suivante → "compounding improvement" +- **Engagement LinkedIn**: 43 likes, 8 commentaires (relativement faible pour 64K followers — signal de niche) + +--- + +## 🎯 Score de pertinence (1-5) + +| 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 | + +**Score: 2/5** (après challenge) + +**Justification:** + +La majorité du contenu est déjà couverte dans le guide: +- Plan mode pour tâches non-triviales → documenté (section plan mode) +- Subagent strategy → documenté (section subagents) +- Compounding via CLAUDE.md → documenté (ligne ~3989) +- "Would a staff engineer approve this?" → documenté (ligne 14274) +- Ralph Loop avec PROGRESS.md → couvre le même besoin que tasks/lessons.md (ligne 1575-1595) +- Simplicity / No Laziness / Minimal Impact → PRINCIPLES.md et CLAUDE.md best practices + +**Delta réel = tasks/lessons.md comme convention alternative** — un fichier runtime créé pendant le travail (vs CLAUDE.md qui est une config upfront). C'est une différence d'implémentation, pas un concept nouveau. + +--- + +## ⚖️ Comparatif + +| Aspect | Cette ressource | Notre guide | +|--------|----------------|-------------| +| Plan mode (tâches non-triviales) | ✅ Couvert | ✅ Présent | +| Subagent strategy | ✅ Couvert | ✅ Présent | +| Persistent memory via fichier | ✅ `tasks/lessons.md` | ✅ Ralph Loop (PROGRESS.md) + Serena MCP | +| "Staff engineer approval" check | ✅ Couvert | ✅ Présent (ligne 14274) | +| Self-improvement / compounding | ✅ Pattern spécifique | ✅ CLAUDE.md compounding (ligne ~3989) | +| Autonomous bug fixing (principe) | ✅ Explicite | ⚠️ Implicite, non nommé | +| Demand Elegance (principe nommé) | ✅ Nommé | ⚠️ Implicite (YAGNI, KISS) | +| tasks/lessons.md convention | ✅ Runtime file | ❌ Non documenté comme tel | + +--- + +## 📍 Recommandations + +**Score 2/5 → Mention uniquement, pas d'intégration majeure.** + +**Raisons du score modéré:** +1. **Attribution incertaine**: Le post LinkedIn est une source secondaire. Le tweet @bcherny est une source primaire potentielle mais non fetchable. Intégrer sans vérification = risque de duplication avec attribution inférieure aux sources primaires déjà dans le guide. +2. **Contenu majoritairement redondant**: 5 des 6 workflow practices existent déjà dans le guide sous d'autres formulations. +3. **Delta réel = nommage**: `tasks/lessons.md` vs `PROGRESS.md` + CLAUDE.md = même concept, convention différente. + +**Si source primaire confirmée (bcherny tweet direct):** Score → 3/5 + +Action recommandée: +- **Option 1 (minimale)**: Ajouter `tasks/lessons.md` comme exemple alternatif dans la section Ralph Loop (ligne ~1590), une ligne de mention +- **Option 2 (si confirmé Cherny)**: Créer un court callout "Boris Cherny's lessons.md pattern" dans la section Memory Files comme implémentation légère sans MCP + +**Où si intégration:** +- `guide/ultimate-guide.md` ligne ~1590 (Fresh Context Pattern / Ralph Loop) +- `examples/claude-md/` — ajouter un template avec `tasks/lessons.md` convention + +--- + +## 🔥 Challenge (agent technique) + +**Score challengé: 2/5 (depuis 3/5)** + +Points du challenge: +- **Attribution non vérifiée**: "Basé sur Boris Cherny" via un post LinkedIn secondaire → ne pas traiter comme source primaire. Le guide a déjà des sources primaires vérifiées (InfoQ Jan 2026, paddo.dev, Twitter officiel de Cherny). +- **tasks/lessons.md = CLAUDE.md dans un dossier tasks/**: Différence de convention, pas de substance. La valeur ajoutée est quasi-nulle si le pattern est "write rules to a markdown file". +- **5/6 practices déjà dans le guide**: La redondance est élevée. +- **Seul point potentiellement nouveau**: "Autonomous Bug Fixing" comme principe autonome nommé explicitement — le guide ne l'articule pas comme tel ("just fix it, zero context switching"). +- **"Demand Elegance"**: Intéressant comme formulation, mais KISS/YAGNI couvrent l'intention. + +**Risques de non-intégration**: Quasi nuls — le guide couvre l'essentiel via des sources meilleures. + +--- + +## ✅ Fact-Check + +| Affirmation | Vérifiée | Source | +|-------------|----------|--------| +| Stanislav Beliaev: 64,853 followers | ✅ | LinkedIn fetch direct | +| Date publication: Feb 19, 2026 | ✅ | LinkedIn fetch direct | +| "Based on Boris Cherny best practices" | ⚠️ | Secondaire — tweet @bcherny non fetchable | +| Boris Cherny = créateur Claude Code @ Anthropic | ✅ | Documenté dans le guide (ligne 15153) | +| 43 likes, 8 commentaires | ✅ | LinkedIn fetch direct | + +**Stats non vérifiées**: Attribution directe à Boris Cherny — le tweet @bcherny référencé n'a pas pu être fetchable (JS requis sur X). La source primaire existe potentiellement mais n'est pas vérifiable sans accès X authentifié. + +**Aucune hallucination de chiffres détectée.** + +--- + +## 🎯 Décision finale + +- **Score final: 2/5** +- **Action: Mention uniquement** — Ajouter une ligne dans la section Ralph Loop/Fresh Context Pattern mentionnant la convention `tasks/lessons.md` comme alternative lightweight +- **Condition pour réévaluation**: Confirmation que le tweet @bcherny/status/2017742741636321619 contient du contenu inédit non déjà capturé via ses sources primaires existantes +- **Confiance: Moyenne** — Contenu vérifié mais attribution primaire non confirmable + +**Pas d'intégration majeure recommandée en l'état.** diff --git a/guide/ultimate-guide.md b/guide/ultimate-guide.md index 686145c..395627d 100644 --- a/guide/ultimate-guide.md +++ b/guide/ultimate-guide.md @@ -1595,6 +1595,18 @@ while :; do cat TASK.md PROGRESS.md | claude -p ; done - `PROGRESS.md` — Learnings, completed tasks, blockers - Git commits — Each iteration commits atomically +**Variant: tasks/lessons.md** + +A lightweight alternative for interactive sessions (no loop required): after each user correction, Claude updates `tasks/lessons.md` with the rule to avoid the same mistake. Reviewed at the start of each new session. + +``` +tasks/ +├── todo.md # Current plan (checkable items) +└── lessons.md # Rules accumulated from corrections +``` + +The difference from PROGRESS.md: `lessons.md` captures *behavioral rules* ("always diff before marking done", "never mock without asking") rather than task state. It compounds over time — the mistake rate drops as the ruleset grows. + | Traditional | Fresh Context | |-------------|---------------| | Accumulate in chat history | Reset per task |