marketing-shibata50/claude-code-ultimate-guide
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
claude-code-ultimate-guide/machine-readable
History
Florian BRUNIAUX a5942f1c53 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>
2026-02-01 21:30:34 +01:00
..
claude-code-releases.yaml docs: track Claude Code v2.1.27 release 2026-01-31 16:19:51 +01:00
cowork-reference.yaml docs: complete Cowork documentation v1.0 (Phase 2) 2026-01-20 11:23:43 +01:00
llms.txt feat: add ecosystem positioning, install script & new commands 2026-01-19 08:42:33 +01:00
README.md refactor: restructure repo into thematic directories v3.1.0 2026-01-13 15:30:02 +01:00
reference.yaml docs: add Addy Osmani spec-writing evaluation (4/5) + spec-first.md sections 2026-02-01 21:30:34 +01:00

README.md

Machine-Readable References

Files optimized for LLM/AI consumption.

Contents

File Description Tokens
reference.yaml Structured index with line numbers for deep dives ~2K
llms.txt Standard LLM context file for repository indexation ~1.5K

Usage

Give Claude Code instant expertise

# Paste into any AI assistant
curl -sL https://raw.githubusercontent.com/FlorianBruniaux/claude-code-ultimate-guide/main/machine-readable/reference.yaml

Reference in Claude Code

@machine-readable/reference.yaml

Add to system prompts

Include the YAML content in your AI assistant's system prompt for Claude Code expertise.

Back to main README