marketing-shibata50/claude-code-ultimate-guide
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
claude-code-ultimate-guide/guide/workflows
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
..
design-to-code.md feat(guide): add Pencil (IDE-native canvas) to Product Designer workflow 2026-01-22 10:16:20 +01:00
exploration-workflow.md docs: add AI productivity research, trust calibration, and exploration workflow 2026-01-19 19:16:33 +01:00
iterative-refinement.md release: v3.20.0 - Multi-Agent Code Review Automation 2026-01-30 16:07:09 +01:00
pdf-generation.md feat(seo): add CITATION.cff and improve AI discoverability 2026-01-17 11:21:58 +01:00
plan-driven.md docs: add task management workflow and update guides 2026-01-26 14:02:54 +01:00
README.md release: v3.20.3 - Competitive Analysis Gaps (claudelog.com) 2026-01-31 21:55:12 +01:00
search-tools-mastery.md docs: add grepai benchmark data to search tools workflow 2026-01-25 18:35:38 +01:00
skeleton-projects.md release: v3.20.3 - Competitive Analysis Gaps (claudelog.com) 2026-01-31 21:55:12 +01:00
spec-first.md docs: add Addy Osmani spec-writing evaluation (4/5) + spec-first.md sections 2026-02-01 21:30:34 +01:00
task-management.md docs: document Tasks API field visibility limitations (Gang Rui analysis) 2026-01-27 16:16:49 +01:00
tdd-with-claude.md docs: add task management workflow and update guides 2026-01-26 14:02:54 +01:00
tts-setup.md docs: add Agent Vibes TTS integration documentation (v3.11.1) 2026-01-22 16:08:32 +01:00

README.md

Claude Code Workflows

Step-by-step guides for common development patterns with Claude Code.

🔍 Search & Discovery

Search Tools Mastery ⭐ NEW

Master the art of code search by combining rg, grepai, Serena & ast-grep

Learn when to use each tool, how to combine them for maximum efficiency, and real-world workflows including:

  • Exploring unknown codebases
  • Large-scale refactoring
  • Security audits
  • Framework migrations
  • Performance optimization

Key Topics:

  • Quick decision matrix
  • Complete feature comparison
  • 5 combined workflows
  • Performance benchmarks
  • Common pitfalls
  • Tool selection cheatsheet

🎯 Development Workflows

Plan-Driven Development

Structure complex tasks with planning mode before execution.

When to use: Multi-step features, architectural changes, uncertainty about approach

TDD with Claude

Test-Driven Development workflow: write tests first, implement after.

When to use: Critical functionality, regression prevention, API design

Spec-First Development

Write specifications before code for better requirements clarity.

When to use: Team collaboration, complex features, documentation-first projects

Iterative Refinement

Improve code through multiple refinement cycles.

When to use: Quality improvements, performance optimization, code cleanup

Skeleton Projects ⭐ NEW

Use existing battle-tested repositories as scaffolding for new projects.

When to use: Starting new projects, standardizing team patterns, rapid prototyping from proven foundations

🎨 Design & Content

Design to Code

Convert design mockups (Figma, wireframes) into working code.

When to use: Frontend development, UI implementation, design system work

PDF Generation

Generate professional PDFs using Quarto/Typst with Claude Code.

When to use: Reports, documentation, whitepapers, technical documents

TTS Setup

Configure Text-to-Speech for Claude Code responses (Agent Vibes integration).

When to use: Audio feedback, accessibility, hands-free coding

🔬 Code Exploration

Exploration Workflow

Systematically explore and understand unfamiliar codebases.

When to use: New projects, legacy code, documentation gaps

Related: See Search Tools Mastery for advanced multi-tool exploration strategies.

Quick Selection Guide

Your Situation Recommended Workflow
New to codebase Exploration Workflow + Search Tools Mastery
Complex feature Plan-Driven or Spec-First
Need reliability TDD with Claude
Large refactoring Search Tools Mastery
UI implementation Design to Code
Code quality Iterative Refinement
New project from template Skeleton Projects
Documentation PDF Generation
Audio feedback TTS Setup

Contributing

New workflow ideas? Open an issue or PR in the main repository.

Workflow Template Structure:

  1. Title & Purpose
  2. When to Use
  3. Prerequisites
  4. Step-by-Step Guide
  5. Real-World Examples
  6. Common Pitfalls
  7. Related Workflows

Last updated: January 2026