Devdocs Onboard

项目上下文

生成项目上下文摘要，帮助 AI 工具或团队成员快速了解项目并接手工作。

运行模式

/devdocs-onboard              → 智能检测（询问读或写）
/devdocs-onboard --read       → 只读取现有文档，不修改
/devdocs-onboard --update     → 强制重新扫描更新

智能检测流程

检测 00-context.md 是否存在
        │
        ├── 不存在 → 自动进入更新模式
        │
        └── 存在 → 询问用户
                    ├── "读取现有内容" → 展示文档，不修改
                    └── "重新扫描更新" → 扫描项目，覆盖文件

语言规则

• 支持中英文提问
• 统一中文回复
• 使用中文生成文档

触发条件

• 用户切换 AI 工具，需要传递上下文
• 用户开始新的对话会话
• 团队成员需要了解项目
• 用户要求生成项目简报

核心理念

上下文传递问题

会话 A (Claude Code)          会话 B (新 AI 工具)
        │                            │
        ├── 了解项目结构              │ ← 需要重新了解
        ├── 读取设计文档              │ ← 需要重新读取
        ├── 理解当前进度              │ ← 需要重新理解
        └── 知道下一步任务            │ ← 需要重新确认
                                     │
                    ┌────────────────┘
                    ▼
             /devdocs-onboard
                    │
                    ▼
            生成上下文摘要
                    │
                    ▼
             快速接手项目

核心原则：

• 一份文档包含所有关键上下文
• 新 AI 读取后能立即开始工作
• 避免重复探索和询问

工作流程

1. 扫描 DevDocs 文档
   │
   ▼
2. 提取关键信息
   ├── 项目概述
   ├── 技术架构
   ├── 当前进度
   └── 待办任务
   │
   ▼
3. 扫描代码库结构
   │
   ▼
4. 生成上下文摘要
   │
   ▼
5. 输出文件（可直接传递给新 AI）

输出文件

主文件：docs/devdocs/00-context.md

此文件设计为可直接复制给新 AI 工具作为初始上下文。

文档结构

# 项目上下文：<项目名称>

**生成时间**：YYYY-MM-DD HH:mm
**生成工具**：/devdocs-onboard

---

## 1. 项目概述

### 1.1 项目目标
<从 01-requirements.md 提取>

### 1.2 核心功能
| 编号 | 功能 | 状态 |
|------|------|------|
| F-001 | <功能名称> | ✅ 已完成 / 🔄 进行中 / ⏳ 待开发 |

### 1.3 技术栈
<从 02-system-design.md 提取>

---

## 2. 系统架构

### 2.1 架构概览
<从 02-system-design.md 提取架构图>

### 2.2 核心模块
| 模块 | 职责 | 关键文件 |
|------|------|----------|
| <模块名> | <职责> | `src/xxx/` |

### 2.3 核心接口
<从 02-system-design.md 提取关键接口签名>

---

## 3. 代码结构

### 3.1 目录结构

<实际项目目录结构，通过 ls/tree 获取>

### 3.2 关键文件说明
| 文件 | 用途 |
|------|------|
| `src/index.ts` | 入口文件 |
| `src/config.ts` | 配置管理 |

---

## 4. 当前进度

### 4.1 总体进度
| 类型 | 总数 | 已完成 | 进行中 | 完成率 |
|------|------|--------|--------|--------|
| 功能点 | X | X | X | XX% |
| 开发任务 | X | X | X | XX% |

### 4.2 最近完成
- T-05: <任务名称> (YYYY-MM-DD)
- T-04: <任务名称> (YYYY-MM-DD)

### 4.3 当前进行中
- T-06: <任务名称>
  - 状态：<进度描述>
  - 涉及文件：`src/xxx.ts`

### 4.4 未提交变更
<如有未提交的代码变更，列出>

---

## 5. 待办任务

### 5.1 下一步任务
| 优先级 | 任务 | 依赖 | 关联需求 |
|--------|------|------|----------|
| P0 | T-07: <任务名称> | T-06 | F-002, AC-005 |

### 5.2 阻塞项
<如有阻塞项，列出>

---

## 6. 重要约定

### 6.1 编码规范
- 遵循 MTE 原则（可维护、可测试、可扩展）
- 函数不超过 50 行
- 参数不超过 5 个

### 6.2 测试要求
- 单元测试覆盖率 ≥ 80%
- 禁止弱断言

### 6.3 提交规范
<从 git log 提取项目提交风格>

---

## 7. 快速开始

### 7.1 环境准备
```bash
<安装依赖命令>

7.2 运行项目

<运行命令>

7.3 运行测试

<测试命令>

8. DevDocs 文档索引

接手建议：

1. 先阅读本文档了解全貌
2. 查看"当前进行中"任务状态
3. 从"下一步任务"继续开发
4. 遇到细节问题查阅对应 DevDocs 文档

## 信息提取规则

### 从 DevDocs 提取

| 信息 | 来源文档 | 提取内容 |
|------|----------|----------|
| 项目目标 | `01-requirements.md` | 需求背景、目标用户 |
| 功能列表 | `01-requirements.md` | F-XXX 功能点及状态 |
| 技术栈 | `02-system-design.md` | 技术选型表 |
| 架构图 | `02-system-design.md` | 架构概览图 |
| 核心接口 | `02-system-design.md` | 接口签名表 |
| 当前进度 | `04-dev-tasks.md` | 执行检查清单 |
| 待办任务 | `04-dev-tasks.md` | 未完成的 T-XX |

### 从代码库提取

| 信息 | 提取方法 |
|------|----------|
| 目录结构 | `ls -la` 或 `tree` |
| 关键文件 | 分析 package.json、入口文件 |
| 未提交变更 | `git status` |
| 提交风格 | `git log --oneline -5` |
| 运行命令 | 从 package.json scripts 或 Makefile 提取 |

## 使用场景

### 场景一：完成工作，准备交接（--update）

用户: /devdocs-onboard --update

Agent: 正在扫描项目并生成上下文... ✅ 已更新 docs/devdocs/00-context.md

您可以将此文件内容复制给新的 AI 工具，它将快速了解项目并接手工作。

### 场景二：新 AI 接手项目（--read）

用户: /devdocs-onboard --read

Agent: 正在读取项目上下文...

[展示 00-context.md 内容]

当前进度：8/12 任务已完成 (67%) 下一步：T-09 用户认证模块

建议从"待办任务"部分继续开发。

### 场景三：不确定时（智能检测）

用户: /devdocs-onboard

Agent: 检测到 docs/devdocs/00-context.md 已存在（更新于 2 小时前）

请选择：

1. 读取现有内容（不修改）
2. 重新扫描更新

用户: 1

Agent: [展示现有文档内容]

## 约束

### 生成约束

- [ ] **必须扫描所有 DevDocs 文档**
- [ ] **必须检查当前代码库状态**
- [ ] **必须包含未提交变更信息**
- [ ] 输出文件必须自包含（不依赖外部链接理解）
- [ ] 关键信息必须直接展示（不只是引用文档路径）

### 内容约束

- [ ] **项目概述不超过 200 字**
- [ ] **架构图必须包含（ASCII 或 Mermaid）**
- [ ] **必须列出下一步可执行的任务**
- [ ] 敏感信息（密钥、密码）不得包含
- [ ] 文件路径必须准确可访问

### 更新约束

- [ ] 每次生成覆盖旧文件
- [ ] 生成时间必须记录
- [ ] 如 DevDocs 不存在，提示用户先运行相关 skill

## Skill 协作

| 场景 | 协作 Skill | 说明 |
|------|-----------|------|
| DevDocs 不存在 | `/devdocs-retrofit` | 先从代码逆向生成文档 |
| 进度信息过时 | `/devdocs-sync` | 先同步文档状态 |
| 需要详细任务 | `/devdocs-dev-tasks` | 查看完整任务列表 |

## 命令选项

```bash
# 智能检测：根据文档存在状态询问用户
/devdocs-onboard

# 只读模式：读取并展示现有文档，不做任何修改
/devdocs-onboard --read

# 更新模式：强制重新扫描项目并更新文档
/devdocs-onboard --update

下一步

交接方（工具 A）

1. 完成阶段性工作后，运行 /devdocs-onboard --update
2. 将 00-context.md 内容传递给新 AI 工具

接手方（工具 B）

1. 运行 /devdocs-onboard --read 了解项目
2. 从"待办任务"部分继续开发
3. 完成工作后运行 /devdocs-onboard --update 更新上下文