ai-native-doc-system

AI Native Doc System

AI Native Doc System 是一套面向 AI 辅助开发的 Markdown 文档系统和 skill 工作流。它基于 Matt Pocock skills 的中文本地化版本，结合 BMad Method 的复杂项目工作流，以及 AI-native 文档实践整理而成。

这个仓库不是从零开始写的一组 skills。更准确地说，它是一个整合与再设计项目：把已有 engineering skills 接入同一条文档链，并补充 PRD、Plan、Spec、Issue、BMad 融合和长期真相源规则。

Why It Exists

AI 编码真正难的不是“让 AI 写代码”，而是让 AI 在每次新会话里读到正确上下文，并知道什么内容是正式约束。

这个仓库解决四个问题：

• 把领域语言、架构决策、产品需求、规格说明和任务切片统一维护在仓库内。
• 让 producer skills 生成同一套 PRD -> PLAN -> SPEC -> issues 文档链。
• 让工程类 skills 在实现、诊断、测试和重构前读取同一套项目上下文。
• 在复杂项目中接入 BMad，同时保持 docs/ 作为长期真相源。

核心原则：

docs/ 是长期真相源。
skills 负责生成、读取和维护文档产物。
BMad 负责展开、审计和执行；AI-native 文档负责裁决、沉淀和控制。

Provenance

本仓库建立在以下来源之上：

• mattpocock/skills：原始上游项目，提供多种 agent skills 的基础设计和实现。
• vinvcn/mattpocock-skills-zh-CN：Matt Pocock skills 的简体中文本地化版本，是本仓库中多数组件的直接上游来源。
• BMad Method：提供复杂项目中的 agent、workflow、readiness、story cycle、review 和 retrospective 思路。本仓库没有把 BMad 复制成另一套真相源，而是将其作为 AI-native 文档系统的可选升级路径。
• 本仓库：补充 AI-native 文档系统规范、BMad 融合规则、to-plan、to-spec、BMad-aware to-issues、setup 配置文档，以及面向长期真相源的 skill 改造。

详细来源、派生目录和改动说明见 THIRD_PARTY_NOTICES.md。

Documentation

• AI_DOCUMENT_SYSTEM.md：AI-native 文档系统核心规范。
• BMAD_INTEGRATION.md：BMad 与 AI-native 文档系统的真相源、晋升和冲突规则。
• LEVEL3_BMAD_WORKFLOW.md：严肃项目中的 BMad + AI-native 节点流程。
• THIRD_PARTY_NOTICES.md：上游来源、派生内容和改动说明。

Skills

AI-native Document Producers

• setup-ai-document-system：在目标仓库中初始化 agent adapter 和 docs/agents/*.md 配置。
• grill-with-docs：围绕领域语言、边界和长期技术决策进行追问，并更新 CONTEXT.md / ADR。
• to-prd：把对话上下文整理为 docs/features/<feature>/PRD.md。
• to-plan：生成可选阶段计划，放在 docs/plans/ 或 docs/features/<feature>/PLAN.md。
• to-spec：把 PRD / Plan 转成带验证命令的 docs/features/<feature>/SPEC.md。
• to-issues：把 Spec / Plan 拆成可执行的 vertical-slice issues；在 BMad story cycle 中只生成控制面板 issues。

Engineering Workflow Skills

• diagnose：纪律化 bug / performance regression diagnosis loop。
• tdd：使用 red-green-refactor loop 做 test-driven development。
• triage：基于 issue tracker 和 triage labels 管理 incoming issues。
• zoom-out：在不熟悉代码区域时生成模块、调用方、文档和决策地图。
• improve-codebase-architecture：寻找 deepening opportunities，改善 testability 和 AI-navigability。
• prototype：构建 throwaway prototype 来验证状态模型、业务逻辑或 UI 方向。

Productivity And Support Skills

• caveman：超压缩沟通模式。
• grill-me：围绕计划或设计持续追问，直到达成共同理解。
• handoff：把当前 conversation 压缩成可交接文档。
• write-a-skill：创建结构正确、支持 progressive disclosure 的新 agent skills。
• git-guardrails-claude-code：设置 Claude Code hooks，阻止危险 git commands。
• migrate-to-shoehorn：将 test files 从 as type assertions 迁移到 @total-typescript/shoehorn。
• scaffold-exercises：创建 exercises 目录结构。
• setup-pre-commit：设置 Husky、lint-staged、typecheck 和测试 hook。

Quick Start

把需要的 skills 复制到目标仓库的 .agents/skills/ 目录，或使用支持 .claude-plugin/plugin.json 的 installer 安装本仓库 active skills。

最小推荐集合：

skills/setup-ai-document-system
skills/grill-with-docs
skills/to-prd
skills/to-plan
skills/to-spec
skills/to-issues

首次使用顺序：

1. 安装或复制需要的 skills 到目标仓库。
2. 运行 setup-ai-document-system，建立目标仓库自己的 agent adapter 和 docs/agents/*.md 配置。
3. 使用 grill-with-docs 收敛领域语言、边界和长期决策。
4. 按需要运行 to-prd -> to-plan（可选）-> to-spec -> to-issues。
5. 执行阶段根据任务选择 diagnose、tdd、triage、prototype、zoom-out 或 improve-codebase-architecture。
6. 复杂项目需要 BMad 时，参考 BMAD_INTEGRATION.md 和 LEVEL3_BMAD_WORKFLOW.md。

Target Repository Layout

这是推荐结构，不是强制模板。项目已有 AGENTS.md、CLAUDE.md 或其他工具入口时，应把它们视为 agent adapter。

/
├── AGENTS.md / CLAUDE.md / other agent adapter
├── CONTEXT.md
├── README.md
├── docs/
│   ├── agents/
│   │   ├── document-system.md
│   │   ├── domain.md
│   │   ├── issue-tracker.md
│   │   └── triage-labels.md
│   ├── adr/
│   ├── plans/
│   └── features/
│       └── <feature>/
│           ├── PRD.md
│           ├── PLAN.md
│           ├── SPEC.md
│           └── issues/
└── .agents/
    └── skills/

PLAN.md 是可选文档。只有当功能、版本或跨功能交付需要明确阶段和顺序时才创建。

Validation

修改 skill、manifest 或 README 后，运行：

node scripts/validate-skills.mjs

当前验证脚本会检查 .claude-plugin/plugin.json 中列出的 active skills 是否存在，并确认 README 中提及这些 skill。

后续可在 fixtures/minimal-target/ 增加一个最小目标仓库样例，用来验证这些 skills 假设的文档结构。这个 fixture 应作为 smoke test 输入，而不是新的工作流规范；真正的规范仍以 docs/AI_DOCUMENT_SYSTEM.md 为准。

License And Attribution

本项目使用 MIT License。

本仓库包含来自 vinvcn/mattpocock-skills-zh-CN 的派生 skill 内容；该项目基于 Matt Pocock 的 MIT 授权项目 mattpocock/skills。BMad 相关内容来自对 BMad Method 工作流和本地 BMad skills 的融合整理。

完整来源、改动说明和署名信息见 THIRD_PARTY_NOTICES.md。