全生命周期开发助手 (Dev Plan Assistant)

> 「先想清楚，再做干净，最后记得复盘」 — 覆盖规划、开发、回顾三个阶段的完整开发闭环。

核心理念

这个 skill 不是帮你写代码，而是帮你避免写出不需要的代码。它确保你在正确的时间做正确的事：

• 开发前：想清楚要做什么、有没有现成方案
• 开发中：模块进度有迹可循、不遗漏不重复
• 开发后：Bug 可追溯、经验可沉淀

三阶段生命周期

┌────────────── 阶段一：规划 ──────────────┐
│  1.1 反问理解需求                         │
│  1.2 GitHub 技术调研（避免重复造轮子）⚠️    │
│  1.3 扫描项目生成模板（从现有代码提取模式）  │
│  1.4 制定开发计划 + 生成 VuePress 站点     │
│  1.5 生成 CLAUDE.md（一次性，给 AI 看的）   │
├────────────── 阶段二：开发 ──────────────┤
│  2.1 模块启动 → 创建模块开发计划           │
│  2.2 模块更新 → 更新进度状态               │
│  2.3 模块完成 → 标记 completed，更新计划   │
├────────────── 阶段三：回顾 ──────────────┤
│  3.1 Bug 文档（按需）                      │
│  3.2 测试文档（按需）                      │
│  3.3 总结文档（按需）                      │
└──────────────────────────────────────────┘

触发规则

轻量模式

触发词：「轻量模式」「不需要站点」「只要文档」

区别：

轻量模式目录结构：

docs/
├── 01-需求分析.md
├── 02-技术调研.md
├── 03-模板中心/
│   ├── 前端开发模板.md
│   └── 后端开发模板.md
├── 04-开发计划/
│   ├── README.md
│   └── 001-模块开发.md
├── 05-开发规范.md
└── 06-项目跟踪/
    ├── bugs/
    ├── tests/
    └── summaries/

适用场景：
- 小型项目、个人工具
- 不需要在线文档预览
- 已有其他文档系统（Notion、飞书等）

阶段一：规划（开发前）

> 详细流程见 references/phase1-planning.md

1.1 反问理解需求

在写任何代码之前，通过反问把需求搞清楚：
- 目标用户是谁？核心功能是什么？
- 技术偏好？交互形式？规模预期？
- 总结需求让用户确认：「我理解你要做的是 XXX，对吗？」

1.2 技术调研（避免重复造轮子）⚠️

> 详细方法论见 references/research-methodology.md

跳过条件：如果项目文件夹中已有现有项目代码（非从零开始的新项目），直接跳过本步骤，进入 1.3 扫描项目生成模板。

这是最关键的阶段。在动手写代码之前，必须确认没有现成的开源方案。

多层次搜索策略：
1. 提炼 3-5 组中英文搜索关键词
2. 搜索类似开源项目（awesome-selfhosted, openalternative.co, alternativeto.net）
3. 搜索工具库和框架（npm, PyPI, GitHub topics）
4. 搜索模板和脚手架

六维评估体系：Activity / Adoption / Security / License / Docs / Fit

反偏见过滤：交叉验证 3+ 独立来源，优先客观指标

1.3 扫描项目生成模板

> 详细流程见 references/phase1-template.md

在写开发计划之前，先扫描项目现有代码，提取已有的模式做成模板文档。这不是代码规范，而是从实际代码中提取的「项目已经怎么做的」快照。

扫描内容：
- 前端：全局 API 调用方式、store 结构、通用组件、路由模式
- 后端：全局配置、中间件、错误处理、数据库操作模式
- 全栈：目录结构、文件命名规律、模块组织方式

输出：docs/03-模板中心/，前端/后端各一个完整模板文档，包含技术栈、目录结构、代码骨架、编码规范和开发 Checklist。

全新项目（无现有代码）：
- 跳过扫描步骤
- 使用 assets/default-templates/ 中的默认模板库
- 展示模板索引，让用户选择技术栈
- 复制对应模板到 docs/03-模板中心/

1.4 制定开发计划 + 生成站点

一个模块一个计划文档，写入 docs/04-开发计划/。

标准模式：完成模板扫描后将 assets/vuepress-template/ 复制到项目 docs/，运行 npm install && npm run docs:dev。

轻量模式：不复制 VuePress 模板，直接创建 Markdown 文件，无需 npm install。

1.5 生成 CLAUDE.md（一次性）

> 详细流程见 references/claude-md-generation.md

在规划阶段完成后，自动生成 CLAUDE.md — 这是给 AI 看的「项目说明书」。

关键约束：
- 只执行一次 — 通过 .claude-md-generated 标记文件判断，后续调用不重复生成
- 已有则补充 — 如果 CLAUDE.md 已存在，追加缺失章节，不覆盖原有内容
- 产品经理思维 — 用户可能不懂技术、描述模糊、用词不专业，AI 需要理解真实意图后翻译成技术语言写入

执行时机：
- 全新项目 → 1.4 之后生成
- 已有项目 → 1.3 扫描模板后补充

CLAUDE.md 包含：项目背景、技术栈、目录结构、核心功能、开发规范、特殊说明、用户偏好

阶段二：开发（开发中）

> 详细流程见 references/phase2-development.md

自动行为

模块完成后 Git 提醒

触发时机：模块开发完成后

模块开发完成
    ↓
询问用户：「模块已完成，是否需要提交并推送到远程仓库？」
    ↓
┌─────────────────────────────────────┐
│ 用户选择：                           │
│ • 是 → 执行提交推送流程              │
│ • 否 → 跳过，继续开发                │
│ • 稍后 → 记录待提交状态              │
└─────────────────────────────────────┘
    ↓
检测远程仓库 → git remote -v
    ↓
┌─────────────────────────────────────┐
│ 无远程仓库时：                       │
│ 提醒用户：「当前项目未连接远程仓库，  │
│ 请先添加远程地址：                   │
│ git remote add origin <url>」        │
└─────────────────────────────────────┘
    ↓
执行提交推送

Commit 格式：<type>(<module>): <desc>

一个模块一个计划

模块定义：这里的「模块」是架构师视角的功能域，不是代码层面的小模块。一个模块包含前后端全链路，覆盖完整业务流程。

示例 — 用户认证模块：
- 前端：登录页、注册页、验证码组件、Token 存储、路由守卫
- 后端：登录接口、注册接口、验证码生成/校验、JWT 签发、密码加密
- 数据库：用户表、验证码表、登录日志
- 全流程：注册 → 验证 → 登录 → Token 刷新 → 登出

不拆分成「前端登录模块」「后端登录模块」，而是作为一个完整的功能域，一个文档覆盖前后端全链路。

每个模块独立一个文档，使用模板中心中提取的模式作为参照。模块完成后必须更新计划文档的状态和进度。

默认不主动写文档

开发过程中不主动创建或修改文档，除非：
- 模块启动/完成（自动行为）
- 用户明确要求记录
- AI 判断关键信息需要保存（反问确认后写入）

阶段三：回顾（开发后）

> 详细流程见 references/phase3-review.md

生成仓库文档

触发词：「生成文档」「初始化仓库文档」「生成 README」

扫描项目代码，自动生成双语 README 文档。

输出要求

README 结构模板

# 项目名称

<p align="center">
  <img src="https://img.shields.io/badge/Node-18.x-339933?logo=node.js" />
  <img src="https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript" />
  <img src="https://img.shields.io/badge/License-MIT-blue" />
</p>

> 一句话描述项目用途

---

## 功能

| 功能 | 说明 |
|:-----|:-----|
| 功能A | 描述 |
| 功能B | 描述 |

---

## 快速开始

\```bash
# 安装
npm install

# 运行
npm start
\```

---

## 目录结构

\```
project/
├── src/
│   ├── core/       # 核心模块
│   └── utils/      # 工具函数
└── docs/           # 文档
\```

---

## 许可证

MIT

徽章生成规则

根据项目实际技术栈自动匹配 Shields.io 徽章：

> 徽章颜色遵循各技术栈官方品牌色，格式：https://img.shields.io/badge/<Label>-<Content>-<Color>?logo=<icon>

工作量校准

VuePress 站点结构

docs/
├── .vuepress/config.js
├── README.md               # 首页
├── 01-需求分析/             # 1.1 输出
├── 02-技术调研/             # 1.2 输出
├── 03-模板中心/             # 1.3 输出：从现有代码提取的模式模板
│   ├── README.md           # 模板索引
│   ├── 前端开发模板.md      # 前端完整模板（技术栈+目录+路由+API+状态+规范+Checklist）
│   └── 后端开发模板.md      # 后端完整模板（技术栈+目录+分层+Entity/DTO/VO/Controller/Service模板+数据库规范+规范+Checklist）
├── 04-开发计划/             # 1.4 + 阶段二输出（一个模块一个计划）
│   ├── README.md           # 模块进度总览表
│   ├── 001-用户认证开发.md  # 每个模块独立文档
│   ├── 整体架构.md
│   └── 迭代计划.md
├── 05-开发规范/             # 编码/Git 规范（非模板，是约定规范）
└── 06-项目跟踪/             # 阶段三输出
    ├── README.md
    ├── bugs/
    ├── tests/
    └── summaries/

默认模板库

> 适用于全新项目，在扫描项目模板前作为参考。

位置：assets/default-templates/

前端模板

后端模板

使用方式

1. 新项目启动时：展示模板索引，让用户选择技术栈
2. 复制模板：将对应模板复制到 docs/03-模板中心/
3. 后续开发：按模板开发新模块，保持风格一致

跨平台兼容性

此 skill 设计为跨 AI 平台兼容（Trae、WorkBuddy、Claude Code 等）：

• 不依赖平台特定功能，所有操作通过通用命令完成
• 标准化 Markdown + YAML frontmatter
• 各平台自动适配对应工具

快速参考

用户说「跳过 XX」时

• 跳过阶段一（需求理解）→ 提醒风险，但还是听用户的
• 跳过技术调研 → 已有项目自动跳过；新项目强烈建议不要跳过，但尊重用户决定
• 跳过模板扫描 → 对于新项目可以跳过（没有代码可扫），老项目建议先跑一次
• 跳过生成站点 → 确认是否有其他文档管理方式

最小化运行

如果用户只想快速开始，至少完成：
1. 一段话总结需求
2. 已有项目跳过 GitHub 搜索；新项目至少一次搜索（确认不是重复造轮子）
3. 扫描项目模板（如果有现有代码）
4. 一个简单的模块列表

记住：这个 skill 的目标不是写文档，而是确保每一行代码都值得写。