| name | acoder |
|---|---|
| description | 长时自动化编程系统。用于创建和管理自动化编程项目。支持多文件和描述混合输入。当用户说"创建项目"、"初始化项目"、"执行任务"、"查看进度"、"任务管理"、"代码审查"等时使用。支持命令：init, code, status, list, task, review, help。 |
基于 Anthropic 的长时运行代理研究构建的多项目自动化编程框架，集成 superpowers skills 实现高质量自动化开发。
- Markdown 任务格式: feature_list.md 提供可读性更强的任务描述
- 完整上下文: 每个任务包含背景、需求、技术设计、验收标准
- 自包含: 不引用外部文档，所有信息在一个任务内完整
- 逐个生成: 任务一个一个添加，支持增量迭代
┌─────────────────────────────────────────────────────────────────┐
│ acoder (编排层) │
│ • 项目管理（创建、状态、进度） │
│ • 会话持久化（session_state） │
│ • 分支管理 │
│ • 命令路由 │
└───────────────────────────────┬─────────────────────────────────┘
│ 调用
▼
┌─────────────────────────────────────────────────────────────────┐
│ superpowers skills │
│ writing-plans → subagent-driven-development │
│ verification-before-completion → systematic-debugging │
└─────────────────────────────────────────────────────────────────┘
- 验证优先 - 没有验证就不能声称完成（来自 verification-before-completion）
- 增量进度 - 每次只处理一个任务
- 子代理驱动 - 每个任务新的上下文（来自 subagent-driven-development）
- 两阶段审查 - 规格 → 质量
- 自包含任务 - 每个任务包含完整上下文，不引用外部文档
重要：系统会自动查找和创建工作目录！
.acoder/
└── projects/
└── <项目名>/
├── project.json # 项目配置 + session状态
├── feature_list.json # 任务列表（程序化访问）
├── feature_list.md # 任务列表（可读性更强）
├── findings.md # Bug 和问题记录
├── progress.txt # 进度日志（含 code 阶段执行过程）
└── logs/ # 日志目录
用于记录执行过程中发现的 bug 和问题：
# Findings - Bug 和问题记录
## 待解决问题
### [BUG-001] 登录接口返回 500 错误
- **发现时间**: 2026-03-06 15:30
- **任务**: TASK-004
- **描述**: 登录接口在高并发下返回 500 错误
- **状态**: 待解决
- **优先级**: 高
## 已解决问题
### [BUG-002] 用户名重复注册
- **发现时间**: 2026-03-06 14:00
- **任务**: TASK-005
- **描述**: 相同用户名可以重复注册
- **状态**: 已解决
- **解决时间**: 2026-03-06 14:30每个任务包含以下字段：
## TASK-001: 任务标题
**状态**: ⬜ 待完成 / ✅ 已完成
### 背景 (Background)
{为什么存在这个任务，解决什么问题，在整个项目中的位置}
### 需求 (Requirements)
{具体要实现什么功能，NOT how}
### 技术设计 (Technical Design)
{如何实现：架构、模式、文件位置、代码结构}
### 验收标准 (Acceptance Criteria)
{可测试的完成标准}
### 影响文件 (Files Affected)
- `path/to/file1.ext`
- `path/to/file2.ext`
### 依赖 (Dependencies)
- TASK-XXX (如果有的话)
---用法：
/acoder init <项目名> "需求描述" # 默认不创建分支
/acoder init <项目名> --from <文件> # 从文件创建
/acoder init <项目名> --branch "需求" # 创建分支（使用项目名）
/acoder init <项目名> --branch custom "需求" # 创建自定义分支名
执行流程：
Step 1: 分支处理
────────────────────────────────────────
默认行为：不创建分支，使用当前分支
如果指定 --branch：
- 指定分支名 → 创建指定分支
- 不指定分支名 → 使用项目名作为分支名
Step 2: 脚本创建项目目录
────────────────────────────────────────
python3 acoder.py create <项目名> "描述" [--branch [分支名]]
Step 3: 分析代码库
────────────────────────────────────────
使用 Glob/Grep/Read 分析：
- 项目结构
- 技术栈
- 相关代码
Step 4: 逐个添加任务（Markdown 格式）
────────────────────────────────────────
【重要】一个一个地生成任务，每个任务包含完整上下文
★ 任务拆分原则（科学性）：
────────────────────────────────────────
1. **粒度控制**: 每个任务应能在 30 分钟内完成，确保 AI 能高质量交付
2. **单一职责**: 每个任务只做一件事，避免任务过大导致遗漏或质量下降
3. **可验证性**: 每个任务必须有明确的验收标准
4. **依赖清晰**: 任务间依赖关系明确，形成有向无环图
★ 测试策略（按任务类型）：
────────────────────────────────────────
- **前端任务**:
- 必须使用 Chrome DevTools 插件进行可视化测试
- 验证 UI 渲染、交互响应、响应式布局
- 截图验证关键界面状态
- **后端任务**:
- 必须编写单元测试（核心逻辑覆盖率 > 80%）
- 必须编写集成测试（API 端点全覆盖）
- 测试命令必须在验收标准中明确
对于每个任务：
1. 确定任务 ID 和标题
2. 编写背景（为什么需要这个任务）
3. 编写需求（具体要实现什么）
4. 编写技术设计（如何实现，包括代码结构）
5. 编写验收标准（如何验证完成，包含测试要求）
6. 列出影响的文件
7. 调用脚本保存：
python3 acoder.py add-task-md <项目名> <任务ID> <标题> \
--bg "背景内容" \
--req "需求内容" \
--tech "技术设计内容" \
--accept "验收标准" \
--files "file1,file2"
Step 5: 输出结果
────────────────────────────────────────
显示：
- 项目路径
- 分支名
- 任务概览（Phases 可视化）
示例输出：
═══════════════════════════════════════════════════════════════
📊 项目初始化完成: user-auth
═══════════════════════════════════════════════════════════════
分支: user-auth
路径: .acoder/projects/user-auth
───────────────────────────────────────────────────────────────
📋 Phases 概览
───────────────────────────────────────────────────────────────
⬜ Phase 1: 基础结构 (0/3)
- ⬜ TASK-001: 创建用户模型
- ⬜ TASK-002: 实现数据库迁移
- ⬜ TASK-003: 添加配置文件
⬜ Phase 2: 认证功能 (0/4)
- ⬜ TASK-004: 实现登录接口
- ⬜ TASK-005: 实现注册接口
- ⬜ TASK-006: 实现 JWT 生成
- ⬜ TASK-007: 添加权限中间件
───────────────────────────────────────────────────────────────
总计: 0/9 任务完成 (0%)
feature_list.md 已创建，包含完整的任务上下文
═══════════════════════════════════════════════════════════════
用法：
/acoder code <项目名> # 执行一个任务
/acoder code <项目名> --loop # 循环执行所有任务
/acoder code <项目名> <任务ID> # 执行指定任务
执行流程：
Step 1: 获取下一个任务
────────────────────────────────────────
python3 acoder.py next-task <项目名>
Step 2: 获取任务完整上下文
────────────────────────────────────────
python3 acoder.py task-context <项目名> <任务ID>
【重要】这会返回 Markdown 格式的完整任务信息
包括：背景、需求、技术设计、验收标准
Step 3: 更新会话状态
────────────────────────────────────────
python3 acoder.py session <项目名> coding 1 <total>
Step 4: 调用 superpowers:subagent-driven-development
────────────────────────────────────────
【重要】使用 Skill 工具调用
调用: Skill(skill="superpowers:subagent-driven-development")
传入完整任务上下文（从 step 2 获取的 Markdown 内容）
★ 代码质量要求：
────────────────────────────────────────
1. **Codex 实时审查**: 写代码时有 Codex 实时 review，确保高质量代码
2. **遵循《代码简化之道》**:
- 函数只做一件事
- 函数参数不超过 3 个
- 避免嵌套超过 2 层
- 变量名揭示意图
- 删除重复代码
- 保持代码简洁可读
3. **Bug 记录机制**:
- 执行过程中发现 bug → 记录到 `findings.md`
- 格式：`[BUG] <任务ID>: <问题描述> - <状态: 待解决/已解决>`
- 后续任务需要优先解决 findings.md 中的问题
执行过程：
1. 派遣实现子代理
- 读取任务的完整上下文
- 根据技术设计实现代码
- 实时接受 Codex 代码审查
- 按照验收标准测试验证
- 发现 bug 记录到 findings.md
2. 派遣规格审查子代理
- 确认代码符合需求
- 如果不符合 → 修复 → 重新审查
3. 派遣代码质量审查子代理
- 检查代码质量（参考《代码简化之道》）
- 如果有问题 → 修复 → 重新审查
Step 5: 验证完成（调用 verification-before-completion）
────────────────────────────────────────
【铁律】没有验证就不能声称完成！
必须运行验证命令并确认输出：
- 测试命令: 查看输出，确认 0 failures
- Linter: 查看输出，确认 0 errors
- 构建: 确认 exit 0
Step 6: 更新任务状态
────────────────────────────────────────
python3 acoder.py update-task <项目名> <任务ID> true
【自动】同时更新 JSON 和 Markdown 文件
Step 7: Git 提交
────────────────────────────────────────
git add <修改的文件>
git commit -m "feat: ..."
Step 8: 更新会话和进度
────────────────────────────────────────
python3 acoder.py session <项目名> <phase> <step+1> <total>
python3 acoder.py phases <项目名> # 显示更新后的状态
★ 更新 progress.txt（记录 code 阶段执行过程）：
────────────────────────────────────────
追加以下内容到 progress.txt：
- 时间:
- 任务: <任务标题>
-
代码实现
- 修改文件: <文件列表>
- 实现要点: <关键实现描述>
-
代码审查
- Codex 审查: <通过/发现问题>
- 发现问题: <问题描述，如有>
-
测试验证
- 单元测试: <通过/失败> - <测试命令输出摘要>
- 集成测试: <通过/失败> - <测试命令输出摘要>
- 前端可视化测试: <通过/跳过> - <Chrome DevTools 验证结果>
-
Bug 记录
- 发现 bug: <数量>
- 已记录到 findings.md: <是/否>
- 状态: <成功/失败>
- Git 提交:
- 备注: <其他说明>
### 2.1 --loop 模式详解
**用法**：`/acoder code <项目名> --loop`
**循环执行逻辑**：
while True: 1. 检查项目是否完成 python3 acoder.py is-complete <项目名>
2. 判断结果
- 如果 complete=True → 输出完成报告，停止循环
- 如果 complete=False → 继续下一步
3. 执行下一个任务（上述 Step 1-8 流程）
4. 任务执行成功 → 自动继续下一个任务（无需用户确认）
5. 任务执行失败/遇到错误 → 停止循环，等待用户处理
**停止条件**：
- 所有任务完成（is-complete 返回 complete=True）
- 任务执行失败或遇到错误
- 用户中断
**注意事项**：
- `--loop` 模式下任务执行成功后**不会**等待用户确认，直接执行下一个
- 遇到错误时停止，需要用户手动处理后重新运行
- 建议先用 `/acoder code <项目名>` 执行一个任务确认流程正常，再用 `--loop`
---
### 3. STATUS - 查看项目状态
**用法**：
/acoder status <项目名>
**输出格式**：
═══════════════════════════════════════════════════════════════ 📊 项目状态: user-auth ═══════════════════════════════════════════════════════════════
状态: 🔄 running 分支: user-auth 进度: 3/9 (33%)
─────────────────────────────────────────────────────────────── 📋 Phases 状态 ───────────────────────────────────────────────────────────────
✅ Phase 1: 基础结构 (3/3) ✓ - ✅ TASK-001: 创建用户模型 - ✅ TASK-002: 实现数据库迁移 - ✅ TASK-003: 添加配置文件
🔄 Phase 2: 认证功能 (0/4) - ⬜ TASK-004: 实现登录接口 ← 当前 - ⬜ TASK-005: 实现注册接口 - ⬜ TASK-006: 实现 JWT 生成 - ⬜ TASK-007: 添加权限中间件
─────────────────────────────────────────────────────────────── 会话: Phase 2, Step 0/4
📄 查看完整任务列表: cat .acoder/projects/user-auth/feature_list.md ═══════════════════════════════════════════════════════════════
---
### 4. LIST - 列出所有项目
**用法**：
/acoder list
---
### 5. TASK - 任务管理
**用法**：
/acoder task list <项目名> # 列出任务 /acoder task add <项目名> <任务ID> <描述> # 添加任务（简单格式） /acoder task add-md <项目名> # 添加任务（Markdown 格式，交互式） /acoder task context <项目名> <任务ID> # 获取任务完整上下文 /acoder task complete <项目名> <任务ID> # 标记完成
---
### 6. REVIEW - 代码审查
**用法**：
/acoder review <项目名>
调用 `superpowers:requesting-code-review` 进行代码审查。
---
## 工具脚本命令
**路径**: `~/.claude/skills/acoder/acoder.py`
| 命令 | 说明 |
|------|------|
| `create <项目名> [--branch [分支名]]` | 创建项目（默认不创建分支） |
| `load <项目名>` | 加载项目信息 |
| `list` | 列出所有项目 |
| `next-task <项目名>` | 获取下一个待完成任务 |
| `update-task <项目名> <任务ID> <true\|false>` | 更新任务状态 |
| `save-features <项目名> <JSON>` | 保存功能列表（批量） |
| `add-task-md <项目名> <任务ID> <标题> [--bg] [--req] [--tech] [--accept] [--files]` | 添加任务（Markdown） |
| `task-context <项目名> <任务ID>` | 获取任务完整上下文 |
| `session <项目名>` | 获取/更新会话状态 |
| `phases <项目名>` | 获取 phases 状态 |
| `is-complete <项目名>` | 检查项目是否完成 |
---
## 验证门槛（铁律）
**来自 superpowers:verification-before-completion**
在声称任何完成之前必须：
- 识别: 什么命令能证明这个声明？
- 运行: 执行完整的命令
- 读取: 完整输出，检查退出码
- 验证: 输出是否确认声明？
- 只有这样才能: 做出声明
红旗 - 停止：
- 使用 "应该", "可能", "似乎"
- 在验证前表达满意
- 准备提交而没有验证
---
## 快速开始示例
```bash
# 1. 创建新项目（默认不创建分支）
/acoder init user-auth "实现用户认证系统"
# 2. 创建项目并创建分支
/acoder init user-auth "实现用户认证系统" --branch
# 3. 创建项目并使用自定义分支名
/acoder init user-auth "实现用户认证系统" --branch feature-auth
# 4. 查看生成的任务列表
cat .acoder/projects/user-auth/feature_list.md
# 5. 查看项目状态
/acoder status user-auth
# 6. 执行任务
/acoder code user-auth
# 7. 循环执行所有任务
/acoder code user-auth --loop
# 8. 获取某个任务的完整上下文
python3 ~/.claude/skills/acoder/acoder.py task-context user-auth TASK-001
## TASK-001: 创建用户模型
**状态**: ⬜ 待完成
### 背景 (Background)
用户认证系统需要一个持久化的用户数据模型。这是整个认证模块的基础，
后续的登录、注册、权限管理都依赖于这个模型。用户模型需要存储基本
的用户信息，并支持扩展。
### 需求 (Requirements)
1. 用户模型必须包含以下字段：
- id: 唯一标识符 (UUID)
- email: 用户邮箱，唯一，用于登录
- password_hash: 加密后的密码
- username: 用户名，可选
- created_at: 创建时间
- updated_at: 更新时间
2. 支持通过 email 查询用户
3. 支持用户创建和更新操作
4. 密码必须使用 bcrypt 加密存储
### 技术设计 (Technical Design)
1. 使用 SQLAlchemy ORM 定义模型
2. 文件位置: `src/models/user.py`
3. 密码加密: 使用 `passlib` 库的 bcrypt
4. 数据库迁移: 使用 Alembic 创建迁移脚本
代码结构:
```python
# src/models/user.py
from sqlalchemy import Column, String, DateTime
from sqlalchemy.dialects.postgresql import UUID
import uuid
class User(Base):
__tablename__ = "users"
id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
email = Column(String(255), unique=True, nullable=False, index=True)
password_hash = Column(String(255), nullable=False)
username = Column(String(100), nullable=True)
created_at = Column(DateTime, nullable=False)
updated_at = Column(DateTime, nullable=False)- User 模型定义完成，包含所有必需字段
- email 字段有唯一约束和索引
- 密码设置时自动进行 bcrypt 加密
- 单元测试通过：创建用户、查询用户、密码验证
- Alembic 迁移脚本已生成
src/models/user.py(新建)src/models/__init__.py(修改，导入 User)migrations/versions/xxx_create_users_table.py(新建)
- 无
---
## 参考
- [Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
- [Superpowers](https://github.com/obra/superpowers)