# project-dev-skill

**Repository Path**: deng-changtao/project-dev-skill

## Basic Information

- **Project Name**: project-dev-skill
- **Description**: 一整套以交付为目标的项目开发工作流Skill，在使用前请一定要阅读每个环节的skill内容，确保你是对流程有整体把控的，需要有两个 Agent 实例进行工作。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 1
- **Created**: 2026-04-29
- **Last Updated**: 2026-05-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Project-Dev Skill

## 一套面向实际交付的七阶段开发工作流

直接让 AI 写代码，最大的风险不是写不出，而是**不知道什么时候该停下来、怎么验证是对的、出了问题怎么回溯**。Project-Dev 把开发过程拆成七个有明确入口和出口的阶段，每阶段有固定产出，不通过不进入下一步。

**版本：2.0** | **适用场景**：新功能开发、模块重构、复杂 Bug 修复

---

## 七阶段模型

```
env     环境识别
  │
plan    需求拆分 + 用例设计
  │
code    编码执行（CC 终端操作）
  │
verify  机器验收
  │
  ├─ 不通过 ─→ repair 修复循环 ─→ verify 重新验收
  │
  └─ 全部通过 ─→ delivery 交付汇总 + 上线清单
                   │
                memory 记忆回写 + 文档同步
```

### 每阶段解决什么问题

| 阶段 | 解决的问题 | 产出物 |
|------|-----------|--------|
| **env** | 开发前不知道 JDK 版本、依赖是否存在、路径约定是什么 | 环境探测报告 + 资源索引 |
| **plan** | 需求一句话，直接写导致范围蔓延、遗漏边界 | 任务拆解表 + 用例设计 + 风险清单 |
| **code** | AI 直接改文件导致不可控变更 | `current_task.md`（变更细节）+ `current_command.md`（执行指令） |
| **verify** | 写完就交，没有验证标准 | 用例执行报告 |
| **repair** | 验收失败后没有结构化的修复流程 | 修复上下文 + 重新验收 |
| **delivery** | 开发完不知道还差什么才能上线 | 上线 Todo 清单 |
| **memory** | 做完就忘，下次同样问题重新踩坑 | 记忆回写 + 文档双写 |

### 为什么是七阶段而不是一次性完成

三个阶段的问题：
- **跳过环境探测** → 按猜测写代码，编译失败才发现 JDK 版本不对
- **跳过用例设计** → 只覆盖主流程，边界条件上线后才暴露
- **跳过独立验收** → 多个 Task 串联失败，无法定位是哪个环节出错

七阶段的核心约束：**每阶段产出固定格式文档，阶段之间通过文档交接，不口头传递信息**。env 的输出是 plan 的输入，plan 的输出是 code 的输入，以此类推。任何阶段缺失文档，流程终止。

---

## A2A 架构：为什么选择 Agent-to-Agent

Project-Dev 采用 Hermes（编排 Agent）+ Claude Code（执行 Agent）的协作模式，而不是让单一 Agent 直接操作代码文件。

### 架构分工

```
┌─────────────────────┐         ┌─────────────────────┐
│   Hermes Agent      │         │   Claude Code (CC)   │
│   (编排 / 决策)      │         │   (执行 / 操作)       │
├─────────────────────┤         ├─────────────────────┤
│ • 需求分析           │         │ • 读取源码           │
│ • 任务拆分           │  指令   │ • 执行编码           │
│ • 用例设计           │──────→  │ • 编译构建           │
│ • 生成变更指令       │ 文件    │ • 写入回执           │
│ • 验收检查           │←──────  │ • 报告执行结果       │
│ • 修复决策           │         │                     │
└─────────────────────┘         └─────────────────────┘
```

### 为什么这样做

**1. 变更可审计**

Hermes 生成的 `current_task.md` 包含完整的变更上下文：涉及文件、行号、旧代码 → 新代码的 diff、业务规则摘录。CC 执行后写入 `dev_result.md` 回执。Hermes 验收时用 `read_file` 逐行核实实际代码是否与指令一致。任何变更都有"指令 → 执行 → 核实"的完整链路。

**2. 修复有上下文**

当验收不通过时，Hermes 将失败原因追加到 `current_task.md`，生成新的修复指令。CC 拿到的是"上一轮做了什么 + 为什么失败 + 这次要改什么"的完整上下文，而不是重新描述问题。多轮修复的信息不会丢失。

**3. 权限隔离**

Hermes 不直接读写项目源码。它只生成指令文件和验收报告。实际的代码变更由用户在 CC 终端中执行。这意味着：
- AI 不会在错误的分支上提交
- AI 不会意外覆盖用户正在编辑的文件
- 用户始终掌握最终执行权

**4. 流程可中断和恢复**

每阶段产出都是持久化文件（`.ai-context/` 目录下）。流程可以在任何阶段中断，下次从最后完成的阶段继续。不需要重新分析需求或重新生成指令。

---

## 快速开始

在 Hermes Agent 中说以下关键词自动激活：

```
开发、新功能、重构、修复复杂Bug、实现XX需求、编码
```

Agent 会先加载 `references/security.md` 检查分支安全，然后从 env 阶段开始逐步推进。每阶段完成后会汇报产出，等待确认后才进入下一阶段。

---

## 子模块

| 文件 | 职责 |
|------|------|
| `references/security.md` | 分支安全红线 |
| `references/env.md` | 环境探测 + 资源索引 |
| `references/plan.md` | 需求拆分 + 用例设计 |
| `references/code.md` | 编码指令生成 + CC 协作流程 |
| `references/verify.md` | 验收标准 |
| `references/repair.md` | 修复循环 |
| `references/delivery.md` | 交付汇总 + 上线清单 |
| `references/memory.md` | 记忆回写 + 文档同步 |