ai需求开发文档生成

概述

docs-for-ai-dev: AI-Ready Documentation Generation Skill

Generate documentation sets that enable AI agents to build complete, production-quality software without human intervention — for any project type.

Core Principle: Full-Chain Traceability

Every piece of information must form a chain. If any link is missing, AI will guess — and guesses produce bugs.

Feature Requirement (D02: Feature Design)
  → Architecture & API (D03/D04: Architecture + API Design)
    → Code Convention & Data Model (D05: Dev Guide)
      → Pixel-Level UI Spec (U02: Visual Spec) — if UI exists
        → Atomic Task (D06: Task List)

Step 0: Project Type Detection

Before writing any docs, determine the project type and select the appropriate stack profile:

This determines:

• Which doc files are required vs optional
• How the API Design doc is structured (IPC commands vs HTTP endpoints vs function signatures)
• Whether Visual Spec docs exist at all

See [references/stack-profiles.md](references/stack-profiles.md) for per-profile doc selection.

Document Set Structure

Universal Docs (ALL projects need these)

UI-Only Docs (projects with graphical interfaces)

Optional Docs (when applicable)

Split rule: No size limits per doc — write as much as needed for completeness. If a single file exceeds 2000 lines, split by topic (architecture→sub-topics, visual-spec→per-page). Add header note explaining split. Update ALL cross-references.

Content Requirements

For detailed per-document content requirements (adapted per project type), see [references/doc-requirements.md](references/doc-requirements.md).

For document template outlines, quality grading (A/B/C), and example snippets, see [references/doc-templates.md](references/doc-templates.md).

For naming conventions across all artifact types, see [references/naming-conventions.md](references/naming-conventions.md).

For key term definitions used across all docs, see [references/glossary.md](references/glossary.md).

Universal principle: The feature-design doc (D02) is the most critical. It defines ALL data model interfaces. If interfaces are incomplete, everything downstream fails. Every field, every type, every enum variant must be explicit — no any, no Record<string, any>, no placeholder types.

Quality Verification Checklist

For the complete 40-point checklist, see [references/quality-checklist.md](references/quality-checklist.md).

10 most critical checks (apply to ALL project types):

1. Traceability: Every feature in D02 has ≥1 task in phase docs
2. Data model completeness: Every struct/interface has full annotations (derive macros, serde tags, validation rules — whatever the project's framework requires)
3. Entity coverage: Every UI component / API endpoint / CLI command has a spec reference and testable identifier
4. Cross-reference integrity: Every task cross-ref points to an existing file and correct section number
5. No broken file references: No references to pre-split/renamed files
6. Consistent enum strategy: Discriminated/tagged unions are used consistently across docs — never untagged/ambiguous patterns
7. Consistent storage authority: Each data type has ONE authority declared in BOTH dev-guide and state-persistence docs
8. Interface registration parity: API command/endpoint registrations match between api-design and dev-guide exactly
9. Design token consistency: Non-authority docs use implementation variable names (e.g., --color-brand), not shorthand design tokens (e.g., --brand) — unless the authority doc explicitly defines the mapping
10. Deployment completeness: D05 includes deployment section with target platform, packaging, release process, rollback — for ALL project types

AI Consumption Optimization

For 8 detailed patterns, see [references/ai-consumption-patterns.md](references/ai-consumption-patterns.md).

5 key patterns:

1. AGENTS.md as entry point — Keep concise, aim for ≤400 lines. Commands, structure, conventions, pitfalls, doc index
2. Atomic tasks with cross-refs — Each task references specific doc + section. AI loads only what it needs
3. Pixel-level specs (UI projects) — Exact values, not "make it look nice". ASCII art + CSS blocks + state matrices
4. Full struct annotations — Every data model has complete derive/annotation/serde/validator tags. Missing annotations = AI guesses behavior
5. Pitfall list — 8-16 "don't use X, use Y instead" items. Prevents wrong library/pattern choices

Workflow: From Idea to AI-Ready Docs

See [references/workflow.md](references/workflow.md) for the full 8-phase workflow.

Quick summary:

Phase 0: Project Type Detection → select stack profile → determine doc set
Phase 1: Research → findings.md
Phase 2: Overview → D01
Phase 3: Feature Design → D02 (with complete data model interfaces)
Phase 4: Architecture → D03 + D04 (split if >2000 lines)
Phase 5: Visual Specs → U01 + U02-* + U03 (UI projects only)
Phase 6: Dev Guide → D05 + D09 + D06-* (per phase)
Phase 7: Supporting Docs → D07 + D08 + O01-* (as applicable)
Phase 8: Audit & Fix → 4 rounds minimum

Audit Protocol

4 rounds minimum after all docs are written:

Round 1: Structural — All files exist? No oversized files? No stale references? README/AGENTS match actual files?

Round 2: Traceability — Every feature has task? Every task has valid cross-ref? Every entity has spec? Every data model has full annotations? Dependencies reference real tasks?

Round 3: Consistency — Enum strategy consistent? Storage authority consistent? API registrations match? Design tokens consistent? No false dependency claims?

Round 4: Depth & Completeness — D04 validation rules per endpoint? D08 backup/DR for DB-backed projects? U01 accessibility testing methodology? O01 alerting thresholds? D05 env-specific config diff?

After each round: Fix ALL issues, commit, push, re-verify. Expect ~30 issues total over 4 rounds → production-ready docs.