# ai-dev

**Repository Path**: lonycn/ai-dev

## Basic Information

- **Project Name**: ai-dev
- **Description**: AI开发流水线任务管理
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-01
- **Last Updated**: 2026-07-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ai-dev · AI 软件研发流水线

把「AI 参与研发」标准化成一套 **Markdown 驱动 + CSV 调度**的半自动工作流。不依赖任何系统，只靠 **Git + Markdown + CSV + AI Agent**，任意项目今天就能用。

> **一句话核心**：不要让 AI 接「大任务」，要让 AI 接「被文档约束的小任务」。

---

## 它解决什么

你不断丢需求进来，AI 自动走完：**需求评审 → 功能设计 → 任务拆解 → 写测试 → 开发 → 测试 → 写说明书**，并在「需求确认 / 代码 Review / 发布」三个关键节点**停下来等人**。看起来像一个长在 Git 仓库里的轻量开发管理系统。

```
需求 → [AI评审] → ⏸人工确认 → [AI设计] → [AI拆任务] →
[AI写测试] → [AI开发] → ⏸人工Review → [AI写说明书] → ⏸人工发布
```

**人审关卡 = CSV 里的状态闸门。** 调度脚本只挑 `status=todo & owner=ai & 依赖已满足` 的任务执行；`review`/`blocked`/`owner=human` 一律跳过，等人改状态才推进。脚本负责「喂任务」，不负责「过闸门」——所以 AI 不会一路狂奔到生产。

---

## 30 秒看懂结构

每个项目根目录生成一个 `.ai-dev/`：

```
.ai-dev/
├── tasks.csv          # ★ 任务总索引（调度脚本读这个）
├── 00-project/        # 项目基础文档（AI 工作前必读，需你补齐）
├── 01-requirements/   # 需求三态：raw → reviewed → ⏸approved
├── 02-features/       # 每个功能一个文件夹，含 _index.md 导航页
├── 03-tasks/          # 每个任务一个 MD（限定修改范围、验收标准）
├── 04-tests/          # 测试用例 / bug 清单
├── 05-release/        # 发布计划 / 回滚方案
├── 06-prompts/        # 9 个阶段 Prompt
├── 07-handbook/       # 功能说明书（对外交付物，树形 + 截图）
└── 99-logs/           # 执行日志
```

**双层任务库**：`tasks.csv` 做索引（脚本快速扫描），长内容（修改范围、验收标准）放各 `TASK-xxx.md`。

---

## 快速上手（3 步）

```bash
# 1. 在你的项目里初始化（幂等，不覆盖已有文件）
bash <ai-dev路径>/scripts/init.sh /path/to/your-project

# 2. 补齐 .ai-dev/00-project/ 下的项目基础文档（项目简介/技术栈/规范）
#    再把原始需求写进 01-requirements/raw/，让 AI 评审：
#    「读 06-prompts/01-requirement-review.md，处理 raw/xxx.md，只评审不写代码」

# 3. 拆完任务后，跑任务循环
bash <ai-dev路径>/scripts/watch.sh /path/to/your-project --once          # 先跑一轮验证
bash <ai-dev路径>/scripts/watch.sh /path/to/your-project --interval 30   # 持续监听
```

`watch.sh` 会自动挑出下一个可执行任务、喂给 `claude -p`、按结果更新 CSV 状态。

---

## ⚠️ 两条血泪经验（来自踩过坑的实践者，请认真看）

这套方法的两个**已知陷阱**，我们已经在设计里专门对治：

### 1. 「文档驱动 = 你真得仔细读文档，否则做出来全偏」

文档驱动开发最大的坑：AI**看起来读了文档，其实没对齐意图**，越做越偏。

**我们的对治**：`04-coding-agent` 写代码前**强制做「对齐确认」**——先用自己的话复述任务目标、列出关键约束、说明实现思路、暴露存疑点。**存疑点涉及核心业务规则就直接 `blocked`，不许猜。** 你 Review 时先看这段对齐确认，对不齐当场打回，别等代码写完。

### 2. 「文档太多了，大几百个，没人看得过来」

文档爆炸是这类工作流的必然副作用。

**我们的对治三件套**：
- **每个 Feature 一个 `_index.md` 导航页**：一句话目标 + 关键决策 + 文档地图（按重要性排序 + 可信度标注 ✅已评审/⚠️待确认/🚧草稿）。**别人接手只读这一页就懂全貌。**
- **别为生成而生成**：没有数据库变更就不写 database-design，纯后端就不写 frontend-design。质量 > 数量，宁缺空洞占位。
- **可信度标注**：文档地图里每个文档标可信度，让你知道哪些能信、哪些可能过时。

> 即便如此，**这套方法仍要求你认真 Review 关键文档**（尤其 `feature-brief.md` 的功能边界、`_index.md` 的关键决策）。工具能减轻负担，但替代不了人对意图的把关。这是方法的固有属性，不是缺陷。

---

## 工作纪律（决定成败的不是工具，是纪律）

1. **AI 不直接处理模糊需求** —— 先评审出问题清单，再进开发
2. **AI 每次只处理一个 Task** —— 不一次性「把整个系统开发完」
3. **每个 Task 必须限定修改范围** —— 写清「允许修改」和「禁止修改」
4. **写代码前先对齐确认** —— 复述意图、暴露存疑、对不齐就 blocked
5. **Task 完成后更新执行记录 + Feature 索引** —— 保持文档新鲜
6. **发布必须人工审批** —— AI 可生成发布计划，但不能直接发布生产

---

## 9 个阶段 Prompt

| # | Prompt | 角色 | 任务 type |
|---|---|---|---|
| 01 | requirement-review | 产品+技术+测试 | 需求评审 |
| 02 | feature-design | 系统架构师 | `design` |
| 03 | task-breakdown | 研发项目经理 | 拆解 |
| 04 | coding-agent | 开发工程师 | `coding` |
| 05 | test-agent | 测试负责人 | `test` |
| 06 | bugfix-agent | Bug 修复 | `bugfix` |
| 07 | release-agent | 发布负责人 | `release`（人审） |
| 08 | handbook-agent | 文档工程师 | `doc`（说明书） |
| 09 | screenshot-agent | 配图工程师 | 补图（人在场手动触发，不进循环） |

任务之间用 `tasks.csv` 的 `depends_on` 构成 DAG，按依赖顺序执行——这就是「多层阶段」的轻量等价物，不需要额外搭系统。详见 `reference/stages.md`。

---

## 功能说明书（07-handbook）

开发完成后，把功能整理成**面向终端用户**的操作手册，按「用户角色 → 业务模块 → 具体操作」树形组织：

```
07-handbook/用户端/报修/提交工单.md  + screenshots/ + screenshot-checklist.md
```

- `doc` 任务（08）自动生成**文字 + 截图占位 + 截图清单**（可在无头循环里跑）
- **自动截图（09）依赖浏览器，不进循环**——人在场时说「打开chrome 按清单截图」；截不到的保留占位，绝不伪造
- 截图清单是连接「自动生成文字」与「人工/半自动补图」的桥梁

---

## 脚本参数速查

| 命令 | 说明 |
|---|---|
| `watch.sh <dir> --once` | 跑一轮就退出（先用这个验证） |
| `watch.sh <dir> --interval 30` | 持续监听，每 30 秒轮询 |
| `watch.sh <dir> --max 5` | 最多执行 5 个任务后退出 |
| `watch.sh <dir> --idle-exit 3` | 连续 3 轮无任务自动退出 |
| `watch.sh <dir> --retry 2` | failed 后带失败原因反馈给 executor 自动重试（默认 1，0=不重试） |
| `watch.sh <dir> --parallel 3` | 多任务并行（git worktree 隔离，按 feature 隔离，默认 1=串行） |
| `watch.sh <dir> --once --dry-run` | 只看会挑哪个任务，不执行不改状态 |

任务状态：`todo → doing → review → testing → done`，外加 `blocked` / `failed`。
脚本只看 executor 输出的**最后一行** `RESULT=success/failed/blocked` 来更新状态。

---

## 任务看板（可视化）

一个本地小服务，把 `tasks.csv` 和需求渲染成可视化页面（零第三方依赖，纯 Python 标准库 + 原生前端）。

```bash
bash scripts/dashboard.sh <项目目录> --bg --open   # 后台启动并开浏览器
bash scripts/dashboard.sh <项目目录> --stop        # 停止
```

视图：
- **任务看板 / 按 Feature / 依赖 DAG / 统计概览**：从 `tasks.csv` 渲染。点开任务卡片可看详情，并**直接过闸门**：`review→通过/转测试/打回`、`failed→重试`、`blocked→解除阻塞`、`testing→通过/标记失败`（白名单转换，二次确认，写前 `.bak` 备份，同源校验；`release` 类任务永不放开，需人工）。
- **📋 需求**：查看 `01-requirements/` 三态需求（raw/reviewed/approved）。其中 **`raw/` 草稿可在页面直接编辑保存**（带护栏：仅 raw 可写、路径校验防穿越、同源校验防 CSRF、保存前自动 `.bak` 备份）；reviewed/approved 只读。
- 页面内自带「📖 看板使用说明」「🤖 指挥 AI 开发」两份说明。

> 服务仅监听 `127.0.0.1`，不对外。任务可在看板过闸门（白名单转换 + 护栏），但任务内容/拆解仍走 Git；需求仅 raw 草稿可编辑，正式修改仍建议走 Git。

---

## 多模型协作（主调度器 + 子模型 CLI）

`watch.sh` 是**主调度器**，可把不同任务派给不同 AI CLI——**claude / codex / deepseek / opencode / qwen** 等都能领任务、执行任务。这就是「主模型带子模型」：强模型干设计架构，便宜模型干文档测试，省成本。

两个配置文件（init 时复制到项目 `.ai-dev/`，可逐项目定制）：

```
executors.conf   每个 CLI 怎么调（命令模板）
  claude|claude -p {PROMPT} --permission-mode acceptEdits
  codex|codex exec --full-auto {PROMPT}
  qwen|qwen -p {PROMPT} --yolo

routing.conf     哪类任务派给谁
  design|claude     # 设计用强模型
  coding|codex      # 写代码
  doc|qwen          # 文档用便宜模型
```

```bash
bash watch.sh <project> --list-executors          # 看已配置 executor 及本机是否装了
bash watch.sh <project> --once --executor codex   # 强制全程用某模型
```

选模型优先级：`--executor` > 任务行 `executor` 列 > `routing.conf` > 默认 claude。

**关于并发**：默认**串行**（`--parallel 1`，一次一个任务，零冲突）。加 `--parallel N` 开启**并行**：用 git worktree 隔离，每个任务在独立分支执行，verify pass 后 `merge --no-ff` 回主分支，冲突则降级为 `blocked` 并保留分支待人工。**按 feature 隔离**（同一 feature 内仍串行，避免改同一批文件冲突），CSV 写收归主进程串行化。详见 `reference/executors.md`。

> ⚠️ 除 claude 外的命令模板是**按各 CLI 文档的合理推测**，首次用前请跑 `<cli> --help` 校准（不同 CLI 的非交互执行、自动写文件标志不一样，且更新快）。

---

## 深入阅读

| 文档 | 内容 |
|---|---|
| `SKILL.md` | 技能完整说明（Claude Code 入口） |
| `reference/directory-structure.md` | `.ai-dev/` 完整目录 |
| `reference/csv-schema.md` | tasks.csv 字段定义和状态机 |
| `reference/watch-loop.md` | 监听脚本工作原理 |
| `reference/stages.md` | 9 个研发阶段与 DAG |
| `reference/handbook.md` | 功能说明书树形结构与截图 |
| `reference/state-machine.md` | 需求/Feature/Task 三层状态机 |
| `reference/git-conventions.md` | 分支和提交规范 |
| `reference/opencode-integration.md` | **接入 opencode**：把流水线做成 opencode 扩展的设计 |
| `opencode/README.md` | opencode 扩展总览 + `scripts/link-opencode.sh` 接入/更新用法 |
| `tests/README.md` | 自动化测试网：`scripts/serve.py`/`csv_helper.py` 的安全边界与状态机测试 |

---

## 接入 opencode（一行接入，软链即更新）

把 ai-dev 做成 opencode 的 skill/command/tool/agent/plugin，在 opencode 里用 `/ai-dev-next` 等驱动流水线。源在 `opencode/`，用软链接入——**改源即更新，无需重装**。

```bash
bash scripts/link-opencode.sh --global              # 接入：所有项目通用
bash scripts/link-opencode.sh /path/to/project      # 接入：仅某项目
bash scripts/link-opencode.sh --global --dry-run    # 预览 / --unlink 移除
```

**更新**：改 `opencode/` 下已有文件 → 自动生效（软链）；新增/删除文件 → 重跑上面的命令补软链。详见 `opencode/README.md`。

---

## 设计取舍（为什么是这样）

- **为什么半自动而非全自动**：模糊需求和发布环节，人的判断不可替代。闸门用 CSV 状态守住，安全。
- **为什么 CSV + MD 双层**：CSV 适合扫描过滤，长文本塞 CSV 单元格会很难读写。
- **为什么截图不进无头循环**：浏览器自动化在 `claude -p` 无头会话里不稳定，硬塞会卡死任务。
- **为什么不搭多层列表系统**：`depends_on` 已经是 DAG，再叠一层会加剧「文档/结构太多」的问题，违背轻量定位。

> 装上即用，但**第一次请拿一个小需求 `--once` 跑通**，确认 AI 行为可控，再开持续监听。复杂需求拿来当首跑一定会乱——这是纪律，不是工具问题。