agent-harness

Agent Harness

子命令路由

以 /agent-harness <subcommand> 的形式调用时，路由到相应的工作流：

子命令	操作
init <name>	运行 python3 scripts/init_project.py "<name>" --project-dir "$(pwd)"
sprint [req]	执行 Sprint Agent 工作流（参见 references/sprint-agent.md）
code	执行 Coding Agent 工作流（参见 references/coding-agent.md）
996	执行 996 并行编排（参见 references/996-agent.md）
status	运行 python3 scripts/status.py --project-dir "$(pwd)"
archive	运行归档工作流
force-archive	运行强制归档工作流
help 或空值	显示可用命令

用法示例：

• /agent-harness init "My Project" - 初始化新项目
• /agent-harness sprint "Add authentication" - 规划冲刺
• /agent-harness code - 开始编码会话
• /agent-harness 996 - 通过子 Agent 编排执行并行编码
• /agent-harness status - 显示状态

重要：始终操作当前项目目录中的文件，而不是技能目录中的文件。每个工作流开始时，都要运行 python3 scripts/resolve_project_dir.py 获取正确的绝对路径。所有对 features.json 和 progress.md 的读取和写入都使用此路径。

用于通过 Sprint-Coding Agent 循环执行复杂多会话项目的框架。

概述

Agent Harness 让 Claude 能够管理长期项目，具体方式如下：

• Sprint Agent：规划功能并拆解需求
• Coding Agent：逐项实现功能
• 996 Agent：通过子 Agent 编排并行功能实现
• 进度跟踪：在会话之间保留上下文
• 质量关卡：确保每一步都有可运行的代码

命令

Agent Harness 提供支持 Tab 补全的斜杠命令。输入 /agent-harness 可查看所有命令。

/agent-harness

显示可用命令和用法。

输出：

Agent Harness Commands:
  /agent-harness init <name>           - Initialize new project tracking files
  /agent-harness sprint [req]          - Create or update sprint with feature breakdown
  /agent-harness code                  - Start coding session for next feature
  /agent-harness 996                   - Execute parallel coding with subagent orchestration
  /agent-harness status                - Show current project status
  /agent-harness archive               - Archive completed sprints
  /agent-harness force-archive         - Force archive ALL sprints (including incomplete)

/agent-harness init <name>

初始化新项目的跟踪文件。

示例： /agent-harness init My App

操作：

• 创建 features.json 和 progress.md
• 运行 python3 scripts/init_project.py "My App"
• 提交初始化文件：git add features.json progress.md && git commit -m "chore: initialize project tracking"

/agent-harness sprint [requirements]

创建或更新冲刺，并拆解功能。

示例：

• /agent-harness sprint - 审查当前冲刺并规划下一次冲刺
• /agent-harness sprint Add user authentication with email and social login
• /agent-harness sprint Build dashboard with charts and filters

操作：

1. 归档已完成的冲刺（如果有）
2. 分析需求
3. 将需求拆分为包含验收标准的原子功能
4. 仅更新 features.json 和 progress.md——不要创建摘要文档等额外文件
5. 在终端中显示冲刺规划摘要
6. 请求用户确认冲刺计划后再提交
7. 用户确认后，提交：git add features.json progress.md && git commit -m "chore: sprint planning - <sprint-name>"
8. 阅读 sprint-agent.md 了解详细工作流

/agent-harness code

为下一个功能开始编码会话。

操作：

1. 查看 progress.md 和 features.json
2. 选择下一个待处理功能
3. 按照会话协议进行实现
4. 实现后提交代码：git add -A && git commit -m "feat(<scope>): <description>"
5. 阅读 coding-agent.md 了解协议

/agent-harness 996

通过子 Agent 编排并行执行编码任务。

示例：

• /agent-harness 996 - 使用默认设置运行并行编排
• /agent-harness 996 --max-parallel=3 - 将并行子 Agent 数量限制为 3 个

操作：

1. 检查是否有未完成的冲刺
2. 分析依赖关系和文件冲突
3. 分派子 Agent 并行执行
4. 验证结果并更新跟踪文件
5. 提交：git add -A && git commit -m "chore: 996 orchestration complete - N features"
6. 阅读 996-agent.md 了解协议

适用场景： 希望通过并行运行多项编码任务来加快冲刺完成进度时。

/agent-harness status

显示当前项目状态。

输出：

• 当前冲刺及目标
• 功能完成情况统计
• 下一项推荐功能
• 运行 python3 scripts/status.py

/agent-harness archive

归档已完成的冲刺。

操作：

• 列出已完成的冲刺
• 移至 .agent-harness/archived/
• 运行 python3 scripts/archive_sprint.py
• 提交：git add -A && git commit -m "chore: archive completed sprint"

/agent-harness force-archive

强制归档所有冲刺（包括未完成的冲刺）。

警告： 无论冲刺状态如何，都会归档所有冲刺。

操作：

• 列出要归档的所有冲刺
• 向用户确认
• 全部移至 .agent-harness/archived/
• 运行 python3 scripts/archive_sprint.py --force
• 提交：git add -A && git commit -m "chore: force archive all sprints"

快速开始

python3 scripts/init_project.py "Project Name" -d "Description"
python3 scripts/status.py
python3 scripts/validate_structure.py

工作流

1. 冲刺规划（冲刺 Agent）

时机： 新项目或新迭代

1. 分析用户需求
2. 将需求拆分为包含验收标准的原子功能
3. 按依赖关系排序
4. 更新 features.json 和 progress.md

→ 阅读 references/sprint-agent.md，了解工作流、架构和示例

2. 功能实现（编码 Agent）

时机： 每次开发会话

会话协议：

阶段	操作
开始	pwd → 阅读 progress.md → git log → 运行 lint/build
工作	选择一个功能 → 实现 → 测试
结束	更新 progress.md → 更新 features.json → 提交

→ 阅读 references/coding-agent.md，了解协议、测试和架构

3. 迭代

循环：冲刺 Agent → 编码 Agent → 编码 Agent → ... → 冲刺 Agent

核心文件

文件	用途
features.json	冲刺和功能跟踪
progress.md	会话日志——在顶部添加条目
AGENTS.md	项目专属说明

→ 参阅 references/sprint-agent.md 或 references/coding-agent.md，了解架构

脚本

所有脚本都支持使用 --project-dir / -p 指定项目目录。使用斜杠命令时，会自动传入 --project-dir "$(pwd)"。

python3 scripts/resolve_project_dir.py [-s dir]                # Resolve project directory
python3 scripts/init_project.py <name> [-d desc] [-p dir]     # Initialize tracking
python3 scripts/status.py [-p dir]                             # Show status
python3 scripts/validate_structure.py [-p dir]                 # Validate features.json
python3 scripts/archive_sprint.py [-p dir] [--list|--dry-run]  # Archive completed sprints

重要：运行脚本时，始终在命令前加上 $env:PYTHONIOENCODING="utf-8";（Windows GBK 兼容性所必需）。

重要规则

1. 每次会话只处理一个功能 - 不要实现多个功能
2. 始终确保代码可运行 - 不要破坏构建
3. 端到端测试 - 按用户实际使用的方式进行验证
4. 频繁提交 - 小型提交便于回滚
5. 绝不删除功能 - 只更改状态
6. 使用进度日志 - 记录每次会话

参考资料

按 Agent 角色分类：

• sprint-agent.md - 冲刺 Agent：工作流、功能拆分、架构
• coding-agent.md - 编码 Agent：会话协议、测试、架构
• 996-agent.md - 996 Agent：并行编排、子 Agent 分派、冲突检测

完整示例：

• examples.md - features.json、progress.md 和工作流的真实示例