docs: add llms.txt conceptual documentation to Section 9.18
Add comprehensive llms.txt documentation based on Wasp fullstack essentials resource evaluation (score 3/5). Sourced from llmstxt.org spec, not the promotional article. Changes: - New section 9.18.4: Documentation Formats for Agents (llms.txt) - Explains llms.txt standard, format, and use cases - Clarifies complementarity with Context7 MCP (not opposition) - Provides minimal and advanced examples with line numbers - Integration patterns with CLAUDE.md - References this repo's own llms.txt implementation - Updated section numbering (9.18.4-9.18.11) - Updated Section 9.18 TL;DR with new principle - Added reference.yaml entries for llms.txt Resource evaluation: - File: docs/resource-evaluations/wasp-fullstack-essentials-eval.md - Source: Wasp DevRel blog (framework-agnostic insights extracted) - Score: 3/5 (partial integration, promotional content excluded) - Gap identified: Embarrassing to have llms.txt file without explaining concept - Primary source: llmstxt.org specification Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Florian BRUNIAUX
parent
9805b615c5
commit
783c43baed
4 changed files with 573 additions and 44 deletions
|
|
@ -63,7 +63,8 @@ Les documents de travail bruts (prompts Perplexity, audits clients) restent dans
|
|||
| **Zolkos** (/insights deep dive) | 4/5 | **4/5** | ✅ Integrate (architecture + facets) | [zolkos-insights-deep-dive.md](./zolkos-insights-deep-dive.md) |
|
||||
| **Grenier** (Agent/Skill Quality) | 3/5 | **3/5** | ✅ Intégrer partiellement | [grenier-agent-skill-quality.md](./grenier-agent-skill-quality.md) |
|
||||
| **Awesome Claude Skills** (BehiSecc) | 3/5 | **3/5** | ✅ Mention spécialisée | [awesome-claude-skills-github.md](./awesome-claude-skills-github.md) |
|
||||
| **Wasp Fullstack Essentials** (Vinny @ Wasp) | 3/5 | **3/5** | ✅ Intégrer concepts framework-agnostiques | [wasp-fullstack-essentials-eval.md](./wasp-fullstack-essentials-eval.md) |
|
||||
|
||||
---
|
||||
|
||||
**Dernier update**: 2026-02-07 (55 évaluations)
|
||||
**Dernier update**: 2026-02-09 (56 évaluations)
|
||||
|
|
|
|||
211
docs/resource-evaluations/wasp-fullstack-essentials-eval.md
Normal file
211
docs/resource-evaluations/wasp-fullstack-essentials-eval.md
Normal file
|
|
@ -0,0 +1,211 @@
|
|||
# Resource Evaluation: Wasp Blog - Claude Code Fullstack Development Essentials
|
||||
|
||||
**Date**: 2026-02-09
|
||||
**Evaluator**: Claude (Sonnet 4.5)
|
||||
**Status**: Partially integrated (llms.txt concept + background tasks workflow)
|
||||
|
||||
---
|
||||
|
||||
## Resource Details
|
||||
|
||||
**Source**: Blog post (DevRel content)
|
||||
**URL**: https://wasp.sh/blog/2026/01/29/claude-code-fullstack-development-essentials
|
||||
**Title**: "Claude Code Fullstack Development Essentials"
|
||||
**Author**: Vinny (DevRel @ Wasp)
|
||||
**Date**: January 29, 2026
|
||||
**Reading time**: 21 minutes
|
||||
|
||||
**Content type**: Advocacy piece for "3 essentials" approach to Claude Code fullstack development, with Wasp framework promotion
|
||||
|
||||
**Disclaimer**: This is DevRel content for Wasp framework. Framework-specific recommendations excluded from integration.
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Article argues effective Claude Code fullstack development requires only 3 essentials (not complex multi-agent workflows):
|
||||
|
||||
1. **Full-stack debugging visibility**: Use `Ctrl+B` background tasks + Chrome DevTools MCP for autonomous error handling
|
||||
2. **LLM-optimized doc access**: Advocates llms.txt standard over MCP doc servers (~10x context reduction claimed)
|
||||
3. **Opinionated framework selection**: Convention-over-config frameworks reduce Claude's decision load (60-80% boilerplate reduction claimed)
|
||||
|
||||
Includes quotes from Chris McCord (Phoenix creator), Andrej Karpathy, and references Chroma context-rot research. Demonstrates Wasp plugin setup.
|
||||
|
||||
---
|
||||
|
||||
## Evaluation Score: 3/5
|
||||
|
||||
**Rating**: Moderate — Useful addition but not urgent
|
||||
|
||||
### Justification
|
||||
|
||||
**Strengths**:
|
||||
- Identifies 3 real gaps in current guide:
|
||||
1. llms.txt conceptual documentation (file exists in repo, zero docs)
|
||||
2. Background tasks workflow strategy (feature reference only, no workflow)
|
||||
3. Chrome DevTools MCP (zero coverage)
|
||||
- Framework-agnostic insights extractable despite promotional content
|
||||
- References credible sources (Karpathy, Chroma research already in guide)
|
||||
|
||||
**Weaknesses**:
|
||||
- Heavy promotional content for Wasp framework (~40% of article)
|
||||
- Some stats unverifiable or framework-specific ("97% reduction" specific to Wasp)
|
||||
- False dichotomy llms.txt vs MCP (they're complementary, not alternatives)
|
||||
- Chris McCord quote unverifiable independently
|
||||
- Comparison "~10x context reduction llms.txt vs MCP" is biased (compares index file vs tool definitions)
|
||||
|
||||
### Gap Analysis
|
||||
|
||||
| Content | Status in Guide | Action |
|
||||
|---------|----------------|--------|
|
||||
| llms.txt concept/standard | File exists, ZERO conceptual docs | **HIGH PRIORITY** — Integrate concept (embarrassing gap) |
|
||||
| Background tasks workflow | Feature reference only (scattered) | **MEDIUM PRIORITY** — Add workflow strategy |
|
||||
| Chrome DevTools MCP | Zero coverage | **LOW PRIORITY** — Mention in ecosystem |
|
||||
| Convention-over-config for AI | Section 9.18 (AX framework) covers partially | **LOW PRIORITY** — Reinforce existing section |
|
||||
| Wasp framework specifics | Not covered | **EXCLUDED** — Promotional content |
|
||||
|
||||
### Fact-Check
|
||||
|
||||
| Claim | Verified | Notes |
|
||||
|-------|----------|-------|
|
||||
| Author: Vinny, DevRel @ Wasp | ✅ | Direct from article |
|
||||
| Date: January 29, 2026 | ✅ | Direct from article |
|
||||
| Reading time: 21 min | ✅ | Direct from article |
|
||||
| Chris McCord quote ("never used MCP") | ⚠️ | In article, original source not found |
|
||||
| Karpathy quote ("docs should be .md") | ✅ | Attribution coherent |
|
||||
| "60-80% boilerplate reduction" | ⚠️ | Generic stat, no specific source |
|
||||
| "8-line config replaces 500+ lines" (97%) | ⚠️ | Wasp-specific, not generalizable |
|
||||
| "15-30 tools per MCP server" | ⚠️ | Plausible but approximate |
|
||||
| "~10x context reduction llms.txt vs MCP" | ⚠️ | Biased comparison (different purposes) |
|
||||
| Chroma context-rot research | ✅ | Same source already in guide |
|
||||
| Plugin command format | ✅ | Correct syntax |
|
||||
|
||||
**Corrections applied**:
|
||||
- "97% reduction" excluded (Wasp-specific)
|
||||
- "10x llms.txt vs MCP" excluded (biased comparison)
|
||||
- Chris McCord quote cited with reservation (unverified)
|
||||
|
||||
---
|
||||
|
||||
## Integration Decision
|
||||
|
||||
**Score**: 3/5 — Integrate framework-agnostic concepts only
|
||||
|
||||
**Confidence**: Moderate (promotional content, non-generalizable stats, but real gaps identified)
|
||||
|
||||
### Integrated Content
|
||||
|
||||
| Content | File | Location | Priority | Source Used |
|
||||
|---------|------|----------|----------|-------------|
|
||||
| llms.txt standard concept | `guide/ultimate-guide.md` | Section 9.18 new subsection | High | llmstxt.org (NOT this article) |
|
||||
| Background tasks workflow | `guide/ultimate-guide.md` | Section 9.18 or existing background tasks | Medium | Official Claude Code docs |
|
||||
| Chrome DevTools MCP | `guide/mcp-servers-ecosystem.md` | Browser & Debug section | Low | npm package readme |
|
||||
| Convention-over-config reinforcement | `guide/ultimate-guide.md` | Section 9.18.1 (existing AX) | Low | Marmelab/AX (existing) |
|
||||
|
||||
### Excluded Content
|
||||
|
||||
- Wasp framework specifics
|
||||
- Wasp plugin setup walkthrough
|
||||
- Framework-specific statistics
|
||||
- Promotional language
|
||||
|
||||
---
|
||||
|
||||
## Challenge (technical-writer)
|
||||
|
||||
### Score Adjustment: 3/5 (unchanged)
|
||||
|
||||
### Points Missed in Initial Evaluation
|
||||
|
||||
1. **False dichotomy llms.txt vs MCP**: Article presents them as opposed, but they're complementary. Context7 = runtime lookup, llms.txt = pre-optimized docs. Guide should present complementarity.
|
||||
|
||||
2. **CLAUDE.md connection not made**: "Convention-over-config for AI" = indirect argument that opinionated frameworks need less prompt engineering in CLAUDE.md. Connects to Section 9.18 + CLAUDE.md sizing (line 3054).
|
||||
|
||||
3. **Background tasks workflow undervalued**: Most actionable gap. Guide lists Ctrl+B as shortcut but never explains WHEN/WHY to use it.
|
||||
|
||||
4. **Section 9.18 (AX framework) already partially covered**: Initial eval said "zero coverage" for convention-over-config, but Marmelab/AX framework already covers concept. Correction needed.
|
||||
|
||||
### Risks of Non-Integration
|
||||
|
||||
**Low to moderate**. Gaps are real but fixable independently:
|
||||
- llms.txt: Most embarrassing (repo has file without explaining it)
|
||||
- Background tasks workflow: Real UX gap but not critical
|
||||
- Chrome DevTools MCP: Niche, no risk
|
||||
|
||||
### Challenger Recommendation
|
||||
|
||||
> "The 3 action items are valid but should be sourced from better references than this promotional article. llms.txt from llmstxt.org, background tasks from official docs, Chrome DevTools MCP from npm repo."
|
||||
|
||||
---
|
||||
|
||||
## Integration Plan
|
||||
|
||||
### 1. llms.txt Conceptual Documentation (High Priority)
|
||||
|
||||
**File**: `guide/ultimate-guide.md`
|
||||
**Location**: Section 9.18, new subsection after 9.18.3 (Code Discoverability)
|
||||
**Lines**: ~35 lines
|
||||
|
||||
**Content**:
|
||||
- Explain llms.txt standard (link to llmstxt.org, NOT Wasp article)
|
||||
- Note repo already has `machine-readable/llms.txt`
|
||||
- Explain complementarity with Context7 MCP (not opposition)
|
||||
- When to use: static documentation pre-optimization vs runtime lookup
|
||||
|
||||
**Source**: llmstxt.org specification (primary), NOT Wasp blog
|
||||
|
||||
**Also**: Add entry in `machine-readable/reference.yaml`
|
||||
|
||||
---
|
||||
|
||||
### 2. Background Tasks Workflow Strategy (Medium Priority)
|
||||
|
||||
**File**: `guide/ultimate-guide.md`
|
||||
**Location**: Section 9.18 or existing background tasks section
|
||||
**Lines**: ~25 lines
|
||||
|
||||
**Content**:
|
||||
- Transform Ctrl+B feature reference into workflow strategy
|
||||
- When to background: fullstack dev server, long-running processes
|
||||
- Pattern: dev server background + frontend iteration
|
||||
- Context rot prevention: when to bring back to foreground
|
||||
|
||||
**Source**: Official Claude Code documentation
|
||||
|
||||
---
|
||||
|
||||
### 3. Chrome DevTools MCP Mention (Low Priority)
|
||||
|
||||
**File**: `guide/mcp-servers-ecosystem.md`
|
||||
**Location**: "Browser & Debug" section (next to Playwright/Browserbase)
|
||||
**Lines**: ~8 lines
|
||||
|
||||
**Content**:
|
||||
- Brief mention with install command
|
||||
- Positioning vs Playwright MCP (debugging vs testing)
|
||||
- Link to npm package
|
||||
|
||||
**Source**: npm package README
|
||||
|
||||
---
|
||||
|
||||
### 4. Convention-over-Config Reinforcement (Low Priority)
|
||||
|
||||
**File**: `guide/ultimate-guide.md`
|
||||
**Location**: Section 9.18.1 (existing AX Framework)
|
||||
**Lines**: ~12 lines
|
||||
|
||||
**Content**:
|
||||
- Paragraph connecting opinionated frameworks (Rails, Phoenix, Next.js) to CLAUDE.md complexity reduction
|
||||
- DO NOT mention Wasp specifically
|
||||
- Reinforce existing Marmelab/AX content
|
||||
|
||||
**Source**: Existing Section 9.18
|
||||
|
||||
---
|
||||
|
||||
## Revision History
|
||||
|
||||
- 2026-02-09: Initial evaluation completed
|
||||
- 2026-02-09: Challenge review completed (score unchanged, corrections applied)
|
||||
- 2026-02-09: Integration plan finalized
|
||||
Loading…
Add table
Add a link
Reference in a new issue