docs: add Addy Osmani spec-writing evaluation (4/5) + spec-first.md sections

Integration of "How to write a good spec for AI agents" by Addy Osmani:

Evaluation (docs/resource-evaluations/addy-osmani-good-spec.md):
- Score: 4/5 (High Value - Integrate within 1 week)
- Fills gaps: modular design, operational boundaries, command specs
- Fact-checked: credentials verified via Perplexity, all claims sourced
- Challenge phase: technical-writer agent corrected initial 3/5 → 4/5

Spec-First Workflow Updates (guide/workflows/spec-first.md):
- NEW: "Modular Spec Design" section (~50 lines, line 322)
  Pattern: Split large specs into focused files (CLAUDE-[domain].md)
- NEW: "Operational Boundaries" section (~60 lines, line 372)
  Three-tier system: Always/Ask First/Never → maps to Claude Code modes
- NEW: "Command Spec Template" section (~40 lines, line 432)
  Executable command specs with expected outputs & error handling
- NEW: "Anti-Pattern: Monolithic CLAUDE.md" section (~30 lines, line 472)
  Explains cognitive load problem (>200 lines = context pollution)

Reference Index (machine-readable/reference.yaml):
- 8 new entries: spec_first_workflow → spec_osmani_score
- Links to new spec-first.md sections with line numbers
- Source attribution: https://addyosmani.com/blog/good-spec/

Public Facing (README.md):
- Incremented resource evaluations count: 35 → 36

File growth: spec-first.md 327 → 507 lines (+180)
Source: Addy Osmani (former Chrome team, 14y), published Jan 13, 2026

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Florian BRUNIAUX 2026-02-01 21:30:34 +01:00
parent bc86c8ed7f
commit a5942f1c53
4 changed files with 729 additions and 1 deletions

View file

@ -119,6 +119,23 @@ deep_dive:
sandbox_anti_patterns: "guide/sandbox-isolation.md:372"
sandbox_comparison_matrix: "guide/sandbox-isolation.md:306"
sandbox_score: "4/5"
# Third-Party Tools (guide/third-party-tools.md) - Added 2026-02-01
third_party_tools_guide: "guide/third-party-tools.md"
third_party_tools_cost_tracking: "guide/third-party-tools.md:42"
third_party_tools_session_mgmt: "guide/third-party-tools.md:105"
third_party_tools_config_mgmt: "guide/third-party-tools.md:132"
third_party_tools_alternative_uis: "guide/third-party-tools.md:170"
third_party_tools_known_gaps: "guide/third-party-tools.md:259"
third_party_tools_recommendations: "guide/third-party-tools.md:274"
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_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"
third_party_claude_chic: "https://pypi.org/project/claudechic/"
third_party_toad: "https://github.com/batrachianai/toad"
third_party_conductor: "https://docs.conductor.build"
# Visual Reference (ASCII diagrams)
visual_reference: "guide/visual-reference.md"
# Architecture internals (guide/architecture.md)
@ -456,6 +473,15 @@ deep_dive:
smart_hook_dispatching: 6863
# Workflows
skeleton_projects_workflow: "guide/workflows/skeleton-projects.md"
# Spec-First Development (Addy Osmani, Jan 2026)
spec_first_workflow: "guide/workflows/spec-first.md"
spec_modular_design: "guide/workflows/spec-first.md:322"
spec_operational_boundaries: "guide/workflows/spec-first.md:372"
spec_command_template: "guide/workflows/spec-first.md:432"
spec_anti_monolithic: "guide/workflows/spec-first.md:472"
spec_osmani_source: "https://addyosmani.com/blog/good-spec/"
spec_osmani_evaluation: "docs/resource-evaluations/addy-osmani-good-spec.md"
spec_osmani_score: "4/5"
commands_table: 10213
shortcuts_table: 10246
troubleshooting: 10372