adoc

Category: Tools & Productivity | Uploader: KarnaughK | Downloads: 0 | Version: v1.0（Latest）

Agent Doc - 文档驱动开发助手。帮助用户从需求到交付全流程管理：定义项目方向 → 设计功能模块 → 创建迭代计划 → 执行并验证。使用场景：当用户需要启动新项目、设计产品功能、创建开发计划、继续中断的工作时。关键词：文档驱动、项目管理、需求分析、迭代开发、plan、spec、intent

Changelog: Source: GitHub https://github.com/KarnaughK/AIPD

Directory Structure

Current level: Root

📁 examples/
- 📄 sample-intent.md 1.7 KB
- 📄 sample-plan.md 6.6 KB
- 📄 sample-system.md 2.3 KB
📁 references/
- 📄 intent-guide.md 4.2 KB
- 📄 phase-1-init.md 5.0 KB
- 📄 phase-2-design.md 3.6 KB
- 📄 phase-3-plan.md 2.1 KB
- 📄 phase-4-execute.md 2.5 KB
- 📄 phase-5-archive.md 2.3 KB
- 📄 plan-guide.md 4.4 KB
📁 templates/
- 📄 intent.md 739 B
- 📄 plan.md 2.3 KB
- 📄 system.md 1.1 KB
📄 .gitignore 17 B
📄 FUTURE_PLAN.md 2.4 KB
📄 README.md 3.9 KB
📄 README_EN.md 4.0 KB
📄 skill.md 7.4 KB
📄 TECHNICAL_NOTES.md 7.4 KB

SKILL.md

---
name: adoc
description: >
  Agent Doc - 文档驱动开发助手。帮助用户从需求到交付全流程管理：
  定义项目方向 → 设计功能模块 → 创建迭代计划 → 执行并验证。
  使用场景：当用户需要启动新项目、设计产品功能、创建开发计划、继续中断的工作时。
  关键词：文档驱动、项目管理、需求分析、迭代开发、plan、spec、intent
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - AskUserQuestion
  - WebSearch
  - Task
---

# Agent Doc - 文档驱动开发助手

> **核心理念**: 用户只需记住 `/adoc`，AI 自动判断项目状态并推荐下一步行动。

## 核心行为准则

**当用户提出需求或功能时，AI 必须先读取 `_adoc/index.md` 大索引，检查 `business/` 和 `tech/` 各模块中是否已有对应的标准流程（SOP）。**

- **如果找到** → 按已有文档执行，不要重复造轮子
- **如果没找到，且该需求是流程性任务** → 询问用户：
  - 选项 A：现场定义流程，边做边记录
  - 选项 B：先创建 SOP 文档，再执行
  - 选项 C：直接执行，不记录流程

---

## 工作流程

每个阶段的详细指令存放在 `@references/phase-*.md` 中，按需加载。

### 阶段 0: 状态检测（每次 `/adoc` 必执行）

扫描项目，判断当前处于哪个阶段，展示状态并推荐下一步。

1. 检测 `_adoc/` 目录及各文档状态
2. 向用户展示状态面板
3. 根据状态推荐进入哪个阶段，用户确认后加载对应指令文件

状态面板格式：
```
📊 项目状态

_adoc/ 目录:     ✅ / ❌
intent.md:       ✅ / ⚠️ / ❌
business/ 模块:  X 个
tech/ 模块:      X 个
当前计划:        v0.x-xxx / ❌ 无
已归档计划:      X 个

→ 推荐: 阶段 X - xxx
```

### 阶段 1: 初始化项目 — 聊需求，定方向

触发条件: `_adoc/` 不存在，或 `intent.md` 缺失/不完整
目标: 通过对话帮助用户明确项目方向，产出 `intent.md`
详细指引: `@references/phase-1-init.md`

### 阶段 2: 设计功能模块

触发条件: `intent.md` 完整，但 `business/` 为空或模块很少
目标: 基于项目方向，设计具体的业务模块和技术模块，产出 `business/` 和 `tech/` 文档
详细指引: `@references/phase-2-design.md`

### 阶段 3: 创建迭代计划

触发条件: 有 `business/` 模块，但 `plan/` 下无进行中的计划
目标: 确定本次迭代范围，产出可执行的 Plan 文档
详细指引: `@references/phase-3-plan.md`

### 阶段 4: 执行计划 — 加载上下文，继续开发

触发条件: `plan/` 下存在进行中的计划（非 archive/）
目标: 加载上下文，检查进度，继续执行任务
详细指引: `@references/phase-4-execute.md`

### 阶段 5: 归档计划 — 收尾，准备下一轮

触发条件: Plan 中所有任务标记为 `[x]`
目标: 计划完成后归档，更新索引，准备下一轮迭代
详细指引: `@references/phase-5-archive.md`

---

## 文档体系结构

```
_adoc/
├── intent.md              # 唯一，项目方向
├── index.md               # 大索引（入口文件，串联一切）
│
├── business/              # 业务模块（按业务价值划分）
│   └── 模块A/
│       ├── index.md       # 模块索引：核心能力 + SOP 导航
│       └── sop-xxx.md     # 标准流程（按需）
│
├── tech/                  # 技术模块/项目（按技术实现划分）
│   ├── index.md           # 技术模块总索引
│   └── 项目A/
│       ├── index.md       # 项目索引：技术栈 + 文档导航
│       └── sop-deploy.md  # 部署 SOP（按需）
│
└── plan/                  # 迭代计划
    ├── index.md           # 分类索引（按模块组织）
    ├── v0.3-xxx.md        # 进行中的计划
    └── archive/           # 已归档计划
        └── v0.2-xxx.md
```

### 渐进式披露加载顺序

AI 必须按以下顺序加载上下文：

1. **读取 `_adoc/index.md`**（大索引）
   - 了解项目有哪些业务模块、技术模块
   - 看到各模块有哪些 SOP（名称，但无路径）
   - 目的：让 AI 知道"有什么能力"，避免误以为缺失而重复创建

2. **读取模块的 `index.md`**（模块索引）
   - 了解该模块的核心能力和通用规则
   - 看到 SOP 的路径和选择原则
   - 了解依赖关系、产出物等元信息
   - **关键**：模块索引包含的通用规则适用于所有 SOP，必须先读

3. **按需读取具体文档**（SOP、Spec 等）
   - 只有确定要执行某个流程时，才读对应的 SOP
   - 避免一次性加载过多内容

**禁止行为**：
- ❌ 跳过模块 `index.md` 直接读 SOP（会遗漏通用规则）
- ❌ 看到大索引里的 SOP 名称就自己猜路径去读（路径在模块索引里）

### 两大维度

| 维度 | 文档 | 关注点 |
|------|------|--------|
| **业务** | business/ 各模块 | 做什么、为什么做、怎么操作（Spec + SOP 聚合在模块内） |
| **技术** | tech/ 各项目 | 怎么实现、技术约束、部署运维 |

### 文档类型归属

| 文档类型 | 用途 | 归属 |
|---------|------|------|
| **SOP** | 标准流程怎么走 | 归属到对应的 business/ 或 tech/ 模块 |
| **Plan** | 本次迭代做什么 | 保持在 plan/ 顶层，独立于模块 |

---

## 关键规则

### Intent（方向）
- **唯一性**: 一个项目只有一个方向
- **上提原则**: 多个平行方向应上提到共同父层级

### Plan 生命周期
```
创建 → 执行 → 完成 → 归档（移动到 archive/ + 更新 index.md）
```
- `plan/` 根目录下的 .md 文件（排除 index.md）= 进行中
- `plan/archive/` 目录下的文件 = 已完成
- `plan/index.md` = 按模块分类的索引

### Tech 独立性
- 独立于业务层（intent/business/plan）
- 可在任何阶段补充或修改
- 遵循: 先文档 → 开发 → 回写文档

### SOP 渐进式
- 随项目演进逐步补充，下沉到各模块内部
- 记录"怎么操作"而非"为什么这样设计"
- 每个流程一个文件，保持简洁

---

## 错误处理

| 场景 | 处理方式 |
|------|---------|
| 用户不确定方向 | 帮助调研竞品，提出 2-3 个可能方向，不催促 |
| 功能拆分困难 | 提供思考框架（用户视角/数据视角/价值视角） |
| 计划范围过大 | 建议拆分成多个 plan，MVP 优先 |
| 任务受阻 | 明确阻塞原因，讨论解决方案，更新 plan 标记 blocked |

---

## 用户体验要点

1. **状态可见**: 每次调用都展示当前状态
2. **推荐明确**: 基于状态给出清晰的下一步建议
3. **可选择**: 始终提供备选操作
4. **不催促**: 允许用户思考和讨论
5. **保持同步**: 每完成一步就更新文档

---

## 参考文档

- `@references/intent-guide.md` - 如何写好项目方向
- `@references/plan-guide.md` - 迭代计划编写指南
- `@templates/` - 各类文档模板
- `@examples/` - 示例文档

---

## 开始执行

当用户触发 `/adoc` 时:
1. 立即开始阶段 0（状态检测）
2. 根据检测结果展示状态并推荐操作
3. 用户确认后，**读取对应阶段的详细指令文件**，按指令执行
4. 每个阶段完成后提示下一步
5. 遇到问题时提供清晰的解决方案

记住: 这个 Skill 的核心价值是 **让用户专注于业务思考，AI 负责文档组织和流程引导**。

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

adoc

Directory Structure

SKILL.md

Report

Notice