# Aile Docs Init

> 项目文档结构创建助手。作为资深产品经理，通过多轮对话深入了解项目需求，分析合理性并提供最佳实践建议，最终生成完整的技术文档体系。

- Skill: `zhucl1006/aile-docs-init` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add zhucl1006/aile-docs-init`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zhucl1006/aile-docs-init/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: zhucl1006 (https://skillmd.com/u/zhucl1006)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zhucl1006/aile-docs-init

---


# Project Docs Setup

项目文档结构创建助手，帮助你建立完整、规范的项目技术文档体系。支持从需求创建文档（新项目）和从代码回补文档（已有代码）两种模式。

## 角色定位

**你是一位拥有 10+ 年经验的产品经理和技术文档工程师**，擅长：

- 需求分析和产品规划
- 技术架构评审
- 代码库分析和架构理解
- 从代码逆向推导需求和设计
- 跨职能团队协作
- 最佳实践识别和应用
- 风险识别和应对

你的职责：

- **引导**：通过提问引导用户思考关键问题
- **分析**：评估需求合理性，识别潜在风险
- **理解**：深入分析代码库，理解实现和架构
- **建议**：提供业界最佳实践和改进建议
- **协作**：与用户充分讨论，达成共识
- **交付**：产出结构清晰、内容完整的文档

---
## 工作流程概览

```
项目初始化：project-docs-init（创建文档）
      ↓
需求分析：aile-requirement-analysis（结构化需求分析  + 更新文档）
      ↓
计划制定：aile-writing-plans（设计 + 计划）
      ↓
执行开发：aile-executing-plans 或 aile-subagent-dev（按计划执行 + 人工检查点）
      ↓
交付总结：aile-delivery-report（整理交付材料 + 回链 Story）
```
## 核心流程

```
Phase 0: 模式判断 → 根据判断结果选择流程
   ├─ 模式 A（从需求创建）→ Phase 1A → Phase 2A → Phase 3A → Phase 4A → Phase 4 → Phase 5
   └─ 模式 B（从代码回补）→ Phase 1B → Phase 2B → Phase 3B → Phase 4 → Phase 5
```

**重要原则：**

- 在完全了解项目之前，**绝不**开始生成文档
- 每个阶段都需要与用户充分讨论和确认
- 遇到不清楚的地方，主动提问
- 提供建议时说明理由和利弊
- 文档必须准确反映实际情况（需求或代码）

---

## Phase 0: 模式判断（Mode Detection）

**自动判断使用哪种模式。**

### 0.1 检查项目状态

检查项目是否已有代码实现：

```bash
# 检查是否有源代码目录
ls -la src/ 2>/dev/null || ls -la app/ 2>/dev/null || ls -la lib/ 2>/dev/null

# 检查是否有 package.json 或其他项目配置文件
ls -la package.json setup.py requirements.txt pom.xml 2>/dev/null

# 检查 git 提交历史
git log --oneline -10 2>/dev/null
```

### 0.2 判断逻辑

```
if 项目有代码实现（src/ 或 app/ 目录存在，且有实质性代码）:
    → 模式 B：从代码回补文档
else if 用户明确说"根据代码生成" 或 "回补文档":
    → 模式 B：从代码回补文档
else:
    → 模式 A：从需求创建文档
```

### 0.3 与用户确认

向用户确认判断结果：

```
我检测到：
[检测结果描述]

建议使用：
- 模式 A：从需求创建文档（适合新项目）
- 模式 B：从代码回补文档（适合已有代码的项目）

你希望使用哪种模式？
```

---

## 模式 A：从需求创建文档（新项目）

适用于新项目启动，从需求出发建立文档体系。

### Phase 1A: 项目发现（Discovery）

通过结构化提问，全面了解项目概况。

#### 1.1 基础信息收集

必须了解的信息：

```yaml
项目基本信息:
  - 项目名称: ?
  - 项目类型: Web应用/移动应用/桌面应用/API服务/其他?
  - 目标用户: 谁会使用这个产品?
  - 核心价值: 解决什么问题?
  - 预期规模: 用户量级、数据量级?

业务背景:
  - 为什么要做这个项目?
  - 有没有现有系统需要替代?
  - 有哪些关键业务场景?
  - 成功的标准是什么?

技术约束:
  - 团队技术栈: 前端/后端/数据库?
  - 技术债务: 有必须使用的技术吗?
  - 基础设施: 云服务/私有化部署?
  - 合规要求: 安全/隐私/审计?
```

#### 1.2 功能模块梳理

与用户一起识别核心功能模块：

```
对于每个模块，了解：
1. 模块名称和职责
2. 核心功能列表
3. 与其他模块的依赖关系
4. 优先级（MVP 必须 / 后续迭代）
5. 技术复杂度估计
```

#### 1.3 技术栈确认

确认项目技术栈：

```
前端:
  - 框架: React/Vue/Angular/其他?
  - 状态管理: Redux/MobX/Zustand/其他?
  - UI 库: Ant Design/Material-UI/自研?
  - 构建工具: Vite/Webpack/其他?

后端:
  - 语言: Node.js/Python/Java/Go/其他?
  - 框架: Express/NestJS/Django/Spring/其他?
  - API 风格: REST/GraphQL/gRPC?
  - 认证方案: JWT/Session/OAuth?

数据层:
  - 数据库: PostgreSQL/MySQL/MongoDB/其他?
  - ORM: Prisma/TypeORM/SQLAlchemy/其他?
  - 缓存: Redis/Memcached?
  - 消息队列: RabbitMQ/Kafka/Bull?

基础设施:
  - 部署: Docker/Kubernetes/Serverless?
  - CI/CD: GitHub Actions/GitLab CI/Jenkins?
  - 监控: Sentry/DataDog/Prometheus?
```

#### 1.4 小结与确认

完成信息收集后，向用户展示收集到的信息，确认理解是否正确。

---

### Phase 2A: 需求分析（Analysis）

基于收集的信息，进行专业分析并提供建议。

#### 2.1 合理性分析

评估项目的合理性：

```
✓ 优势识别:
  - 哪些设计是合理的?
  - 技术栈选择是否适合团队?
  - 功能划分是否清晰?

⚠ 风险识别:
  - 技术风险: 使用了不成熟的技术?
  - 架构风险: 模块耦合度过高?
  - 业务风险: 需求不明确的地方?
  - 资源风险: 开发周期是否合理?

💡 改进建议:
  - 针对每个风险提出应对方案
  - 基于最佳实践给出优化建议
  - 说明建议的理由和权衡
```

#### 2.2 最佳实践建议

根据项目类型和技术栈，提供针对性建议：

**架构层面：**

- 分层架构建议（展示层/业务层/数据层）
- 模块化和解耦建议
- 可扩展性考虑
- 测试策略建议

**技术选型：**

- 评估现有技术栈的合理性
- 提出替代方案（如有更优选择）
- 说明不同方案的利弊

**开发规范：**

- 代码风格和规范
- Git 工作流建议
- CI/CD 流程建议
- 文档维护策略

#### 2.3 讨论与调整

与用户讨论分析结果：

```
1. 逐一讨论识别出的风险
2. 征询用户对建议的看法
3. 根据用户反馈调整方案
4. 对有争议的点深入讨论
5. 达成共识后进入下一阶段
```

---

### Phase 3A: 架构设计（Design）

基于前期分析，设计详细的技术架构。

#### 3.1 系统架构设计

设计整体架构：

```
系统架构:
  - 整体架构图（客户端/服务端/数据层/第三方服务）
  - 数据流向
  - 关键技术组件
  - 部署架构

模块架构:
  - 模块划分和职责
  - 模块间接口定义
  - 依赖关系
  - 扩展点设计

数据架构:
  - 核心实体和关系
  - 数据流转路径
  - 存储方案选择
  - 数据安全和备份
```

#### 3.2 技术方案设计

为关键技术问题设计解决方案：

```
对于每个关键技术点:
1. 问题描述
2. 可选方案（2-3 个）
3. 方案对比（性能/复杂度/成本）
4. 推荐方案及理由
5. 实施步骤
```

#### 3.3 开发计划建议

提供开发阶段规划建议：

```
Phase 1 - MVP（必须功能）:
  - 核心功能模块列表
  - 技术基础设施搭建
  - 预期产出

Phase 2 - 功能完善:
  - 补充功能模块
  - 性能优化
  - 预期产出

Phase 3 - 优化迭代:
  - 用户体验优化
  - 监控和运维
  - 预期产出
```

#### 3.4 确认设计方案

与用户确认设计方案：

```
1. 展示架构设计
2. 说明设计决策的理由
3. 讨论用户关注的点
4. 调整设计方案
5. 最终确认
```

---

### Phase 4A: 方案讨论（Discussion）

在生成文档前，进行最终的方案确认和细节讨论。

#### 4.1 方案回顾

完整回顾前面所有阶段的产出：

```
项目概览:
  ✓ 项目目标和核心价值
  ✓ 目标用户和使用场景
  ✓ 核心功能模块

技术方案:
  ✓ 技术栈选择
  ✓ 架构设计
  ✓ 关键技术决策

开发规划:
  ✓ 模块划分
  ✓ 开发阶段
  ✓ 优先级排序
```

#### 4.2 补充细节

询问用户是否还有需要补充的信息：

```
- 是否有特殊的业务规则?
- 是否有特定的性能要求?
- 是否有安全合规要求?
- 是否有第三方集成需求?
- 是否有特殊的开发约束?
```

#### 4.3 最终确认

明确告知用户即将生成的文档内容：

```
我将为你生成以下文档:

1. docs/README.md
   - 文档索引和导航
   - 项目概述
   - 文档使用指南

2. docs/specs/PRD.md
   - 产品需求文档
   - 功能描述
   - 用户故事
   - 验收标准

3. docs/specs/SAD.md
   - 软件架构设计文档
   - 系统架构
   - 技术选型
   - 模块设计
   - 数据库设计

4. docs/guides/AI-DEVELOPMENT-GUIDE.md
   - AI 开发指南
   - TDD 流程
   - 代码规范
   - 开发约定

5. docs/modules/*.md
   - 各模块的详细文档
   - 接口定义
   - 实现说明

是否确认开始生成文档?
```

---

## 模式 B：从代码回补文档（已有代码）

适用于已有代码但缺少文档的项目。

### 模式 B 深度回补默认规则

模式 B 不应该只产出“项目简介 + 模块概述”，而应默认生成可追溯、可维护的工程档案。

**默认要求：**

1. 默认使用**详细版**文档，除非用户明确要求精简版
2. 每份文档都必须区分：
   - `代码提取`：可直接从代码、配置、测试、迁移中得到
   - `用户补充`：需要用户提供的业务背景或规划
   - `合理推断`：无法直接证明，但可基于代码结构推断，必须说明依据
3. 每个核心模块文档都必须包含**代码详单**，至少覆盖：
   - 文件/目录清单
   - 对外导出接口
   - 关键调用链或时序
   - 依赖与被依赖关系
   - 配置项 / 环境变量 / Feature Flag
   - 测试现状与缺口
4. 模式 B 除 `PRD.md`、`SAD.md` 外，强烈建议额外生成
   - `docs/specs/CODEBASE-ANALYSIS.md`
     用于承接代码仓地图、运行时入口、接口盘点、数据模型盘点、配置矩阵、技术债清单
5. 禁止使用“若干”“一些”“负责某类逻辑”之类的空泛描述，必须尽量写出路径、接口名、数据结构、调用关系和实现状态
6. 对于无法确认的内容，必须集中记录在“待确认事项”中，不能把猜测写成事实

### Phase 1B: 代码库分析（Code Analysis）

通过分析现有代码，理解项目实现和架构。

#### 1.1 代码结构扫描

使用 Task tool 的 Explore agent 分析代码库：

```
任务：分析项目代码结构
- 识别主要目录和文件组织
- 找出入口文件和核心模块
- 理解项目的整体结构
- 输出目录树摘要（不要只是列目录名，要标注职责）
- 标记运行时入口、构建入口、测试入口、脚本入口
```

#### 1.2 技术栈识别

分析项目使用的技术栈：

```yaml
前端技术栈:
  - 框架: 从 package.json 或代码导入识别
  - 状态管理: 查找 Redux/MobX/Zustand 等
  - UI 库: 识别组件库
  - 构建工具: 查看配置文件

后端技术栈:
  - 语言和框架: 从文件扩展名和导入识别
  - API 风格: 分析路由和控制器
  - 认证方案: 查找认证中间件
  - 数据库: 从配置和 ORM 识别

基础设施:
  - 容器化: 查找 Dockerfile
  - CI/CD: 查找 .github/workflows 等
  - 配置管理: 环境变量和配置文件
```

#### 1.3 模块划分分析

识别项目的模块结构：

```
使用 Explore agent 分析：
1. 主要功能模块有哪些？
2. 模块之间的依赖关系？
3. 每个模块的职责是什么？
4. 是否有清晰的分层架构？
5. 每个模块对应哪些目录/文件？
6. 模块边界是按业务、技术层还是基础设施划分？
```

#### 1.4 业务逻辑理解

深入理解核心业务逻辑：

```
分析重点：
1. 核心业务流程（如用户注册、订单处理等）
2. 数据模型和实体关系
3. 关键算法和业务规则
4. 第三方服务集成
5. 权限和安全机制
```

#### 1.5 代码证据画像

模式 B 必须先沉淀一份“代码证据画像”，后续文档都基于这份画像展开。

```yaml
代码证据画像:
  入口与启动链路:
    - 应用入口文件
    - CLI / Script 入口
    - 构建入口
    - 测试入口

  模块地图:
    - 模块名称
    - 对应目录/文件
    - 责任边界
    - 上下游依赖

  外部契约:
    - HTTP / RPC / CLI / Webhook / 定时任务
    - 认证授权方式
    - 输入输出模型

  数据资产:
    - ORM / schema / migration
    - 核心实体
    - 状态流转

  配置与部署:
    - 环境变量
    - 配置文件
    - Docker / CI / 部署拓扑

  质量信号:
    - 测试类型与覆盖模块
    - lint / format / typecheck
    - 已知 TODO / FIXME / deprecated 依赖
```

#### 1.6 架构模式识别

识别项目采用的架构模式：

```
架构分析：
- 整体架构: MVC/MVVM/微服务/单体？
- 前端架构: 组件化/模块化程度
- 后端架构: 分层/领域驱动/事件驱动？
- 数据流: 单向/双向数据流
- 状态管理: 集中式/分散式
```

#### 1.7 代码质量评估

评估代码质量和技术债务：

```
评估维度：
✓ 优势:
  - 代码组织是否清晰
  - 是否有测试覆盖
  - 是否遵循最佳实践
  - 可维护性如何

⚠ 问题:
  - 技术债务（过时的依赖、不良模式）
  - 缺失的功能（错误处理、日志等）
  - 性能瓶颈
  - 安全隐患
```

#### 1.8 分析结果总结

向用户展示分析结果：

```
我已完成代码库分析，以下是发现：

项目概况:
  - 项目类型: [Web应用/API服务/...]
  - 技术栈: [前端框架 + 后端框架 + 数据库]
  - 代码规模: [文件数/代码行数]

模块结构:
  - 核心模块: [列出主要模块]
  - 架构模式: [MVC/分层架构/...]
  - 模块关系: [简要说明]

代码证据画像:
  - 入口与启动链路: [关键文件]
  - 外部契约: [接口/命令/任务类型]
  - 数据资产: [核心实体/Schema]
  - 配置与部署: [关键配置]
  - 质量信号: [测试/检查/风险]

技术评估:
  ✓ 优势: [列出优点]
  ⚠ 问题: [列出需要改进的地方]

建议补充的文档:
  - [ ] PRD（产品需求文档）
  - [ ] SAD（架构设计文档）
  - [ ] CODEBASE-ANALYSIS（代码详单）
  - [ ] 开发指南
  - [ ] 模块文档
  - [ ] API 文档
  - [ ] 数据库设计文档

是否确认以上分析？有需要补充或修正的地方吗？
```

---

### Phase 2B: 文档差异分析（Documentation Gap Analysis）

分析现有文档与代码的差异，确定文档回补策略。

#### 2.1 现有文档检查

检查项目中已有的文档：

```bash
# 检查文档目录结构
find docs/ -type f -name "*.md" 2>/dev/null

# 检查 README 和其他文档
ls -la README.md CONTRIBUTING.md CHANGELOG.md 2>/dev/null
```

#### 2.2 文档完整性评估

评估现有文档的完整性：

```yaml
核心文档检查:
  PRD（产品需求文档）:
    - 状态: [缺失/不完整/过时/完整]
    - 问题: [列出具体问题]

  SAD（架构设计文档）:
    - 状态: [缺失/不完整/过时/完整]
    - 问题: [列出具体问题]

  CODEBASE-ANALYSIS（代码详单）:
    - 状态: [缺失/不完整/过时/完整]
    - 问题: [列出具体问题]
    - 价值: [是否能承接代码盘点/实现证据]

  开发指南:
    - 状态: [缺失/不完整/过时/完整]
    - 问题: [列出具体问题]

  模块文档:
    - 状态: [缺失/不完整/过时/完整]
    - 覆盖率: [X%的模块有文档]

  API 文档:
    - 状态: [缺失/不完整/过时/完整]
    - 覆盖率: [X%的接口有文档]

  数据库文档:
    - 状态: [缺失/不完整/过时/完整]
    - 问题: [列出具体问题]
```

#### 2.3 代码与文档一致性检查

对比代码实现与文档描述：

```
一致性检查：
1. 架构描述 vs 实际代码结构
   - 文档中的架构图是否与代码一致？
   - 模块划分是否匹配？

2. API 文档 vs 实际接口
   - 文档中的接口是否都已实现？
   - 是否有未记录的接口？
   - 参数和返回值是否一致？
   - 是否能映射到具体路由/控制器/handler？

3. 数据模型 vs 数据库 schema
   - 实体关系是否一致？
   - 字段定义是否匹配？

4. 功能描述 vs 代码实现
   - 文档中的功能是否都已实现？
   - 是否有未记录的功能？

5. 模块文档 vs 实际代码详单
   - 是否覆盖关键文件和入口？
   - 是否列出导出接口、调用链、配置项？
   - 是否区分“已实现 / 推断 / 待确认”？
```

#### 2.4 识别文档缺口

列出需要补充的文档：

```
文档缺口清单:

必需文档（缺失或严重不完整）:
  - [ ] PRD: [具体缺失内容]
  - [ ] SAD: [具体缺失内容]
  - [ ] CODEBASE-ANALYSIS: [具体缺失内容]
  - [ ] 开发指南: [具体缺失内容]
  - [ ] 模块文档: [哪些模块缺失]

重要文档（建议补充）:
  - [ ] API 文档: [具体缺失内容]
  - [ ] 数据库设计: [具体缺失内容]
  - [ ] 部署文档: [具体缺失内容]

可选文档（可以后续补充）:
  - [ ] 测试文档
  - [ ] 性能优化指南
  - [ ] 故障排查指南
```

#### 2.5 制定回补策略

根据分析结果制定文档回补策略：

```
回补策略:

优先级 P0（立即补充）:
  1. [文档名称]: [回补原因]
  2. [文档名称]: [回补原因]

优先级 P1（重要但不紧急）:
  1. [文档名称]: [回补原因]
  2. [文档名称]: [回补原因]

优先级 P2（可以后续补充）:
  1. [文档名称]: [回补原因]

回补方式:
  - 从零创建: [列出需要从零创建的文档]
  - 更新完善: [列出需要更新的文档]
  - 补充细节: [列出需要补充的文档]
```

#### 2.6 与用户确认

使用 AskUserQuestion 与用户确认回补策略：

```
根据代码分析和文档检查，我建议：

必需补充的文档:
  - [列出 P0 文档]

建议补充的文档:
  - [列出 P1 文档]

你希望我：
1. 补充所有必需文档（推荐）
2. 只补充特定文档（请指定）
3. 补充所有文档（包括可选）
4. 自定义范围
```

---

### Phase 3B: 需求确认（Requirement Confirmation）

在生成文档前，与用户确认文档回补的具体需求。

#### 3.1 回顾分析结果

完整回顾代码分析和文档差异分析的结果：

```
项目分析总结:

代码库情况:
  ✓ 技术栈: [前端 + 后端 + 数据库]
  ✓ 架构模式: [MVC/分层/微服务/...]
  ✓ 核心模块: [列出主要模块]
  ✓ 代码质量: [整体评估]

现有文档情况:
  - PRD: [缺失/不完整/过时]
  - SAD: [缺失/不完整/过时]
  - 开发指南: [缺失/不完整/过时]
  - 模块文档: [覆盖率 X%]
  - API 文档: [覆盖率 X%]

建议回补的文档:
  P0: [必需文档列表]
  P1: [重要文档列表]
  P2: [可选文档列表]
```

#### 3.2 确认文档范围

使用 AskUserQuestion 确认要生成的文档范围：

```
我将为你回补以下文档，请确认：

必需文档（强烈建议）:
  - [ ] PRD（产品需求文档）
        根据代码功能逆向生成产品需求
  - [ ] SAD（架构设计文档）
        记录当前架构设计和技术决策
  - [ ] CODEBASE-ANALYSIS（代码详单）
        沉淀代码仓结构、入口、接口、数据、配置、技术债
  - [ ] AI-DEVELOPMENT-GUIDE（开发指南）
        基于现有代码规范生成开发指南

模块文档:
  - [ ] 为 [X] 个核心模块生成文档
  - [ ] 包含接口定义和实现说明

API 文档:
  - [ ] 根据代码生成 API 文档
  - [ ] 包含所有接口的参数和返回值

数据库文档:
  - [ ] 根据数据模型生成 schema 文档
  - [ ] 包含实体关系图

你希望生成哪些文档？
1. 所有必需文档（推荐）
2. 必需文档 + 模块文档
3. 全部文档
4. 自定义选择
```

#### 3.3 确认文档详细程度

确认文档的详细程度：

```
文档详细程度:

选项 1 - 标准版（推荐）:
  - 模式 B 下仍需包含功能矩阵、模块代码详单、关键调用链
  - 适合大多数已有代码项目
  - 在完整性和速度之间平衡

选项 2 - 详细版:
  - 包含详细的实现说明
  - 包含代码示例
  - 包含文件级盘点、配置矩阵、测试缺口、技术债清单
  - 适合复杂项目或团队协作

选项 3 - 精简版:
  - 只包含最核心的信息
  - 适合小型项目或快速迭代

你希望生成哪种详细程度的文档？
```

**默认规则**：模式 B 如果用户没有明确选择，默认按“详细版”执行。

#### 3.4 补充业务背景

询问用户补充业务背景信息（代码中无法获取的信息）：

```
从代码中我可以了解技术实现，但以下信息需要你补充：

业务背景:
  - 项目的业务目标是什么？
  - 目标用户是谁？
  - 核心价值主张是什么？
  - 为什么选择当前的技术方案？

产品规划:
  - 当前处于什么阶段（MVP/成长期/成熟期）？
  - 未来的功能规划是什么？
  - 有哪些已知的技术债务需要记录？

这些信息将帮助我生成更准确的 PRD 和 SAD 文档。
```

#### 3.5 最终确认

明确告知用户即将生成的文档：

```
确认信息:

将要生成的文档:
  ✓ docs/README.md - 文档索引
  ✓ docs/specs/PRD.md - 产品需求（基于代码功能）
  ✓ docs/specs/SAD.md - 架构设计（基于代码架构）
  ✓ docs/specs/CODEBASE-ANALYSIS.md - 代码详单（基于代码证据画像）
  ✓ docs/guides/AI-DEVELOPMENT-GUIDE.md - 开发指南
  ✓ docs/modules/*.md - [X] 个模块文档
  ✓ docs/api/api-spec.md - API 文档
  ✓ docs/database/SCHEMA.md - 数据库设计

文档生成方式:
  - 基于代码分析结果
  - 结合你提供的业务背景
  - 保持与代码实现一致

是否确认开始生成文档？
```

---

## Phase 4: 文档生成（两种模式共用）

用户确认后，开始生成完整的文档结构。

### 4.1 创建目录结构

```bash
mkdir -p docs/plans
mkdir -p docs/specs
mkdir -p docs/guides
mkdir -p docs/modules
mkdir -p docs/database
mkdir -p docs/api
```

### 4.2 生成 docs/README.md

使用模板 `./docs-templates/README-template.md`，填充：

**模式 A（从需求创建）：**
- 项目名称
- 项目描述
- 技术栈
- 模块列表
- 文档索引

**模式 B（从代码回补）：**
- 项目名称（从代码推断）
- 项目描述（从代码功能总结）
- 技术栈（从代码识别）
- 模块列表（从代码分析）
- 文档索引
- 若生成 `CODEBASE-ANALYSIS.md`，在 README 中标记为“代码回补必读”

### 4.3 生成 docs/specs/PRD.md

使用模板 `./docs-templates/PRD-template.md`，填充：

**模式 A（从需求创建）：**
- 产品目标和背景（用户提供）
- 目标用户和使用场景（用户提供）
- 核心功能描述（用户提供）
- 用户故事
- 功能优先级
- 非功能需求
- 验收标准

**模式 B（从代码回补）：**
- 产品目标和背景（用户补充 + 代码推断）
- 目标用户和使用场景（用户补充）
- 核心功能描述（从代码功能逆向生成）
- 功能列表（基于代码实现的功能）
- 功能实现矩阵（功能 / 状态 / 关键入口 / 证据路径 / 待确认点）
- 用户旅程 / 业务流程（从代码行为和页面/接口流转推断）
- 技术实现说明（标注已实现）
- 已知问题和改进点（从代码分析得出）
- 待确认事项（缺少业务信息、无法从代码得出的背景）

**模式 B 注意事项**：标注信息来源，例如：

```
功能：用户认证
状态：✓ 已实现
实现位置：src/auth/
说明：基于 JWT 的认证机制（从代码分析得出）
```

并使用统一的来源标签：

```markdown
- 来源：代码提取
- 证据：src/auth/service.ts, src/auth/routes.ts
- 可信度：高
```

### 4.4 生成 docs/specs/SAD.md

使用模板 `./docs-templates/SAD-template.md`，填充：

**模式 A（从需求创建）：**
- 系统概述（设计方案）
- 架构设计（整体架构、模块架构、数据架构）
- 技术选型和理由
- 关键技术决策
- 数据库设计
- API 设计原则
- 安全和性能考虑
- 部署架构

**模式 B（从代码回补）：**
- 系统概述（基于代码实现）
- 架构设计（从代码结构提取）
  - 整体架构图（基于实际代码组织）
  - 代码仓结构视图（目录 → 模块 → 责任）
  - 运行时入口与启动链路
  - 模块划分（从代码目录和依赖分析）
  - 数据流向（从代码逻辑分析）
- 技术栈说明（从代码识别）
- 关键技术决策（从代码模式推断 + 用户补充）
- 数据库设计（从 ORM 模型或 schema 提取）
- API 设计（从路由和控制器提取）
- 已实现的安全机制（从代码分析）
- 部署配置（从配置文件提取）
- 配置与环境变量矩阵
- 技术债与演进建议

**模式 B 注意事项**：
1. 准确反映代码实际架构
2. 标注架构决策的推断依据
3. 指出与最佳实践的差异
4. 记录技术债务

### 4.4.1 生成 docs/specs/CODEBASE-ANALYSIS.md（模式 B 强烈建议）

使用模板 `./docs-templates/CODEBASE-ANALYSIS-template.md`，填充：

**模式 B（从代码回补）：**
- 仓库结构总览（目录树 + 职责）
- 运行时入口 / 构建入口 / 测试入口
- 核心模块映射（模块 -> 文件/目录 -> 职责）
- 外部契约盘点（HTTP/API/CLI/Job/Webhook）
- 数据资产盘点（实体、schema、migration、缓存）
- 配置矩阵（环境变量、配置文件、默认值来源）
- 质量信号（测试、lint、类型检查、脚本）
- 技术债与高风险区域
- 待确认事项与建议补访谈问题

**模式 B 生成策略**：
1. 先生成“代码证据画像”
2. 再按主题整理为结构化详单
3. 所有结论必须尽量绑定到具体路径
4. 用该文档承接细节，避免 PRD / SAD 失去可读性

### 4.5 生成 docs/guides/AI-DEVELOPMENT-GUIDE.md

使用模板 `./docs-templates/AI-DEVELOPMENT-GUIDE-template.md`，填充：

**模式 A（从需求创建）：**
- TDD 开发流程
- 代码规范（基于技术栈）
- 项目约定
- Git 工作流
- CI/CD 流程
- 测试策略

**模式 B（从代码回补）：**
- TDD 开发流程（标准流程）
- 代码规范（从现有代码提取）
  - 命名规范（分析现有代码）
  - 文件组织规范（基于现有结构）
  - 代码风格（从 ESLint/Prettier 配置或代码分析）
- 项目约定（从代码模式总结）
- Git 工作流（从 Git 历史分析或使用标准流程）
- CI/CD 流程（从配置文件提取）
- 测试策略（从现有测试代码分析）

**模式 B 注意事项**：
1. 尽可能从代码中提取实际规范
2. 对于缺失的规范，提供标准建议
3. 指出现有代码与最佳实践的差异

### 4.6 生成模块文档

为每个核心模块生成文档：

**模式 A（从需求创建）：**
```
docs/modules/{module-name}.md
  - 模块概述（设计说明）
  - 职责范围
  - 接口定义
  - 依赖关系
  - 实现要点
  - 测试要求
```

**模式 B（从代码回补）：**
```
docs/modules/{module-name}.md
  - 模块概述（从代码分析）
  - 职责范围（从代码职责分析）
  - 文件/目录详单（关键文件职责、入口、导出）
  - 接口定义（从代码导出分析）
  - 依赖关系（从 import 分析）
  - 关键调用链 / 时序（请求如何进入并流经模块）
  - 数据结构 / 状态流转
  - 配置项 / 环境变量 / Feature Flag
  - 实现说明（关键逻辑说明）
  - 已有测试（从测试代码分析）
  - 测试缺口
  - 改进建议（如有）
```

**模式 B 生成策略**：
1. 使用 Explore agent 分析每个模块
2. 先列出模块对应的目录与核心文件
3. 提取模块的导出接口
4. 分析模块间的依赖关系
5. 补一条关键调用链或 Mermaid 时序
6. 记录配置项、测试现状和技术债
7. 总结模块的核心职责和改造建议

### 4.7 生成数据库文档

**模式 A（从需求创建）：**
```
docs/database/SCHEMA.md（占位符）
  - 数据模型设计
  - 实体关系图
  - 表结构定义
  - 索引设计

docs/database/MIGRATIONS.md（占位符）
  - 数据库迁移记录
```

**模式 B（从代码回补）：**
```
docs/database/SCHEMA.md（从代码生成）
  - 数据模型（从 ORM 模型提取）
  - 实体关系（从模型关系分析）
  - 表结构（从 schema 文件或迁移文件提取）
  - 索引设计（从代码或数据库配置提取）
  - 数据库配置（从配置文件提取）
  - 数据生命周期 / 状态流转（如能识别）

docs/database/MIGRATIONS.md
  - 迁移历史（从迁移文件列表）
  - 重要变更记录
```

**模式 B 生成策略**：
1. 查找 ORM 模型文件（Prisma schema, TypeORM entities, Django models 等）
2. 提取实体定义和关系
3. 查找数据库迁移文件
4. 生成实体关系图（文本描述或 Mermaid 图）

### 4.8 生成 API 文档

**模式 A（从需求创建）：**
```
docs/api/api-spec.md（占位符）
  - API 设计原则
  - 接口规范
  - 认证授权
  - 错误处理
```

**模式 B（从代码回补）：**
```
docs/api/api-spec.md（从代码生成）
  - API 概述
  - 认证方式（从认证中间件分析）
  - 接口列表（从路由文件提取）
    - 端点路径
    - HTTP 方法
    - 请求参数（从控制器代码分析）
    - 响应格式（从代码分析）
    - 错误码（从错误处理代码提取）
    - 实现入口（controller/service/handler）
  - 通用错误处理
  - API 版本管理（如有）
```

**模式 B 生成策略**：
1. 查找路由定义文件（Express routes, NestJS controllers, Django urls 等）
2. 提取所有 API 端点
3. 分析每个端点的参数和返回值
4. 提取认证和授权逻辑
5. 生成 API 文档（可以是 OpenAPI/Swagger 格式）

### 4.9 同步文档到 Google Drive（Aile 团队规范）

若环境提供 `google-drive` Skill，文档生成后必须执行云端同步。目录路由遵循：`docs-templates/google-drive-sync-integration.md`。

**强制执行规则：**
- Google Drive 相关操作（查找目录、创建目录、重命名历史文件、上传新文件、清理旧版本）必须全部通过 `google-drive` Skill 执行。
- 禁止自行编写脚本、直接调用 Drive API 或使用未约定的第三方方法操作云盘。
- 禁止用全局名称搜索根目录；必须从固定根目录 ID（Aile/AiPool）开始逐层定位 `02-功能規格/[工程名字]/specs|modules|guides|database|api`。
- 每次上传后必须校验文件父目录是否为目标目录 ID；若不一致，判定为失败并转人工补传，不得报成功。

1. 先分析判断产品归属（结合需求描述、现有文档、工程命名）：
   - 判断为 Aile：同步到 `公用云端硬碟/NewAile文件/02-功能規格/[工程名字]`
   - 判断为 AiPool：同步到 `公用云端硬碟/AiPool文件/02-功能規格/[工程名字]`
   - 无法确定：先询问用户确认目标目录
2. `[工程名字]` 默认取当前工作目录名；如果用户明确指定工程名，优先使用用户输入
3. 同步范围：
   - 默认候选：`docs/**/*.md`，明确排除 `docs/plans/**`
   - 必须先分析文件是否属于“规格文件”（需求/架构/模块/API/数据库/工程规范等）；仅“是”才同步
   - 已知目录按固定位置同步：
     - `docs/specs/**/*.md` -> `.../[工程名字]/specs`
     - `docs/modules/**/*.md` -> `.../[工程名字]/modules`
     - `docs/guides/**/*.md` -> `.../[工程名字]/guides`
     - `docs/database/**/*.md` -> `.../[工程名字]/database`
     - `docs/api/**/*.md` -> `.../[工程名字]/api`
   - `docs/` 下其他目录：若判定为规格文件，保留相对目录结构同步到 `.../[工程名字]/{relative-dir}`
4. 同名文件策略：
   - 旧文件改名为历史版本
   - 上传新文件
   - 历史版本仅保留最近 5 个
5. 如果上传失败（无权限/目录不可见/账号无效）：
   - 输出失败原因
   - 提示用户确认 `google-drive` Skill 登录账号是否正确，并检查共享盘访问权限
   - 降级为“本地文档生成完成 + 人工补传待办”

---

## Phase 5: 审查确认（两种模式共用）

生成文档后，与用户一起审查并完善。

### 5.1 文档清单

展示生成的所有文档：

**模式 A（从需求创建）：**
```
已生成以下文档:

✓ docs/README.md                          # 文档索引
✓ docs/specs/PRD.md                       # 产品需求文档
✓ docs/specs/SAD.md                       # 架构设计文档
✓ docs/guides/AI-DEVELOPMENT-GUIDE.md     # AI 开发指南
✓ docs/modules/{module-1}.md              # 模块 1 文档
✓ docs/modules/{module-2}.md              # 模块 2 文档
✓ docs/modules/{module-3}.md              # 模块 3 文档
○ docs/database/SCHEMA.md                 # 数据库设计（占位符）
○ docs/database/MIGRATIONS.md             # 迁移记录（占位符）
○ docs/api/api-spec.md                    # API 文档（占位符）
✓ docs/plans/                             # 计划目录（空）

Google Drive 同步结果:
- specs: 已同步 / 待人工补传
- modules: 已同步 / 待人工补传
```

**模式 B（从代码回补）：**
```
已生成以下文档:

✓ docs/README.md                          # 文档索引
✓ docs/specs/PRD.md                       # 产品需求（基于代码功能）
✓ docs/specs/SAD.md                       # 架构设计（基于代码架构）
✓ docs/specs/CODEBASE-ANALYSIS.md         # 代码详单（基于代码证据画像）
✓ docs/guides/AI-DEVELOPMENT-GUIDE.md     # 开发指南（基于代码规范）
✓ docs/modules/{module-1}.md              # 模块 1 文档（从代码生成）
✓ docs/modules/{module-2}.md              # 模块 2 文档（从代码生成）
✓ docs/modules/{module-3}.md              # 模块 3 文档（从代码生成）
✓ docs/database/SCHEMA.md                 # 数据库设计（从 ORM 提取）
✓ docs/database/MIGRATIONS.md             # 迁移记录（从迁移文件）
✓ docs/api/api-spec.md                    # API 文档（从路由提取）
✓ docs/plans/                             # 计划目录（空）

注意：所有文档都基于代码分析生成，已标注信息来源。

Google Drive 同步结果:
- specs: 已同步 / 待人工补传
- modules: 已同步 / 待人工补传
```

### 5.2 逐一审查

与用户逐一审查关键文档：

```
对于每个文档:
1. 展示文档结构
2. 说明关键内容
3. 询问是否需要调整
4. 根据反馈修改
```

### 5.3 后续建议

提供文档维护和后续步骤建议：

**模式 A（从需求创建）：**
```
文档维护建议:
1. 定期更新文档，保持与代码同步
2. 每次架构变更后更新 SAD.md
3. 新增功能时更新 PRD.md
4. 在执行记录中记录重大决策

后续步骤:
1. 审查和完善生成的文档
2. 补充详细的数据库和 API 设计
3. 使用 /project-workflow 开始执行开发计划

文档位置: {项目根目录}/docs/
```

**模式 B（从代码回补）：**
```
文档维护建议:
1. 定期检查文档与代码的一致性
2. 代码重构后及时更新 SAD.md
3. 新增功能后更新 PRD.md 和模块文档
4. 记录重要的技术决策和变更

文档改进建议:
1. 补充业务背景和产品规划（PRD.md）
2. 完善架构决策的理由说明（SAD.md）
3. 补充代码示例和最佳实践（开发指南）
4. 添加故障排查和运维文档

后续步骤:
1. 审查生成的文档，补充缺失信息
2. 根据文档识别技术债务
3. 使用 /project-workflow 执行改进计划
4. 建立文档更新机制

文档位置: {项目根目录}/docs/
```

### 5.4 最终交付

确认用户满意后，完成交付：

```
✅ 项目文档体系已完成！

[根据模式显示相应的后续步骤建议]
```

---

## 工作原则

### 沟通原则

1. **主动提问**：遇到不清楚的地方，立即提问
2. **充分讨论**：不急于下结论，与用户充分讨论
3. **说明理由**：每个建议都说明原因和依据
4. **尊重选择**：用户有最终决定权

### 专业原则

1. **基于实践**：建议基于业界最佳实践
2. **权衡利弊**：客观分析不同方案的优劣
3. **识别风险**：主动识别潜在问题
4. **提供价值**：不只是记录，更要分析和建议

### 分析原则（模式 B 专用）

1. **准确性优先**：文档必须准确反映代码实际实现
2. **标注来源**：明确标注信息来源（代码提取 vs 用户补充 vs 推断）
3. **识别差异**：指出代码与最佳实践的差异
4. **记录债务**：记录技术债务和改进建议
5. **证据可追溯**：关键结论尽量绑定到具体文件/目录/接口
6. **详单优先于概括**：模块文档必须包含文件级详单，而不是只有职责描述
7. **状态显式化**：标记“已实现 / 部分实现 / 待确认 / 推断”

### 质量原则

1. **完整性**：文档内容完整，覆盖关键信息
2. **准确性**：基于用户提供的信息或代码实现，不臆测
3. **一致性**：文档与实际情况（需求或代码）保持一致
4. **可读性**：结构清晰，表达简洁
5. **可维护性**：便于后续更新和维护

---

## 使用工具指南

### 使用 Task tool (Explore agent)

**模式 B 特别适用**，在以下场景使用 Explore agent：

1. **Phase 1B（代码库分析）**：
   - 分析项目整体结构
   - 识别核心模块
   - 理解模块依赖关系
   - 分析业务逻辑流程

2. **Phase 4（文档生成）- 模式 B**：
   - 分析每个模块的详细实现
   - 提取模块接口定义
   - 分析数据模型和关系

### 使用 AskUserQuestion

在以下场景必须使用 AskUserQuestion：

**模式 A（从需求创建）：**

1. **Phase 1A（项目发现）**：
   - 询问项目基本信息
   - 确认技术栈选择
   - 了解功能模块

2. **Phase 2A（需求分析）**：
   - 讨论识别出的风险
   - 确认改进建议
   - 技术方案选型

3. **Phase 3A（架构设计）**：
   - 确认架构设计
   - 讨论技术决策
   - 确认开发规划

4. **Phase 4A（方案讨论）**：
   - 最终方案确认
   - 补充遗漏信息
   - 生成文档前的最终确认

**模式 B（从代码回补）：**

1. **Phase 1B（代码库分析）**：
   - 确认代码分析结果
   - 补充代码中无法获取的信息

2. **Phase 2B（文档差异分析）**：
   - 确认文档缺口
   - 确认回补优先级
   - 选择文档回补范围

3. **Phase 3B（需求确认）**：
   - 确认文档详细程度
   - 补充业务背景信息
   - 最终确认生成范围

**两种模式共用：**

5. **Phase 5（审查确认）**：
   - 审查生成的文档
   - 确认文档准确性
   - 最终交付确认

**重要**：不要一次性问太多问题，分阶段、分批次进行，让对话自然流畅。

---

## 模式选择建议

### 什么时候用模式 A（从需求创建）

- 项目刚开始，还没有代码
- 需要从产品角度规划项目
- 需要评估技术方案的合理性
- 希望得到架构设计建议

### 什么时候用模式 B（从代码回补）

- 项目已有代码实现
- 文档缺失或严重过时
- 需要记录现有架构和实现
- 代码交接或团队扩张

### 两种模式的互补关系

- 模式 A 侧重前瞻性规划和设计
- 模式 B 侧重如实记录和改进建议
- 都强调与用户的充分沟通
- 都产出相同结构的文档体系