# Agent 工作流套件
一套先评估、再接入的 AI coding agent 工作流规则，适合真实软件项目落地使用。
[](https://github.com/crisxuan/agent-workflow-kit/actions/workflows/docs-check.yml)
[](LICENSE.md)
[English Guide](docs/guide.md) · [中文文档](docs/guide.zh-CN.md) · [English Home](README.md)
---
## 这是什么
Agent Workflow Kit 是一份工具中立的指南，也提供面向 agent 的工作流规则包。它不局限于 Codex：任何 LLM、coding agent 或 agent harness 都可以使用这里的指南、模板和规则。
它主要回答五个问题：
- 这个项目到底需不需要 AI 工作流？
- 应该用最小、标准，还是完整工作流？
- 什么时候需要规格层或变更记忆？
- AI agent 完成任务前必须验证什么？
- 哪些外部操作必须先经过维护者批准？
核心原则很简单：
> 先评估项目风险，再选择能降低真实风险的最小工作流。
## 一眼看懂
```mermaid
flowchart LR
Inspect["检查仓库"]
Score["风险评分
0-16"]
Level["选择级别
0 / 1 / 2 / 3"]
Rules["复制规则
AGENTS.md"]
Verify["用一个
小改动验证"]
Inspect --> Score --> Level --> Rules --> Verify
```
## 为什么需要
| 常见问题 | 本项目提供什么 |
|---|---|
| AI agent 过早开始写代码 | 修改前先检查仓库并做风险评分 |
| 需求散落在聊天记录里 | 只在需要时引入规格层或变更记忆 |
| 没有证据就宣称完成 | 可复制的 `AGENTS.md` 验证与完成标准 |
| 多套工具的计划和规则互相冲突 | 针对 spec、plan、review、hook 和外部操作的冲突规则 |
| 团队希望 agent 行为一致 | 面向 agent 的 Skill 包和可复用模板，便于重复评估 |
## 怎么使用这套工具
| 路径 | 适合场景 |
|---|---|
| 阅读 [中文完整文档](docs/guide.zh-CN.md) 或 [English guide](docs/guide.md) | 手动评估一个项目 |
| 复制 [examples/AGENTS.level-2.md](examples/AGENTS.level-2.md) | 快速得到一份标准工作流起点 |
| 使用 `skills/agent-workflow-kit-zh-cn` 包 | 让 agent 检查仓库并输出工作流决策 |
| 把 Markdown 规则迁移到 Claude、Cursor、Codex、Gemini 或其他 harness | 在多个工具里保持一致行为 |
## 快速开始
1. 打开 [中文完整文档](docs/guide.zh-CN.md) 或 [English guide](docs/guide.md)。
2. 用 0-16 分风险表给项目评分。
3. 按分数选择工作流级别。
4. 复制最小可用的 `AGENTS.md` 模板块。
5. 填入真实的安装、测试、lint、构建和浏览器/E2E 命令。
6. 先用一个小改动验证流程，再作为团队规范推广。
## 工作流级别
| Level | 适合场景 | 典型规则 |
|---|---|---|
| Level 0 | AI 不改代码，或项目是一次性原型 | 不接正式 AI 工作流 |
| Level 1 | 小型但会维护的项目 | 基础 agent 规则和验证命令 |
| Level 2 | 大多数 AI 参与开发的软件项目 | 基础规则、规格层建议、执行纪律、外部操作安全 |
| Level 3 | 生产项目、安全敏感项目、复杂 UI 或多 agent 团队 | Level 2 加审查门和更强验证 |
## 文档入口
| 文档 | 用途 |
|---|---|
| [中文完整文档](docs/guide.zh-CN.md) | 面向维护者的中文完整指南 |
| [English Guide](docs/guide.md) | 英文完整指南 |
| [中文 AGENTS 模板](skills/agent-workflow-kit-zh-cn/references/agents-templates.zh-CN.md) | 中文 Skill 参考，内含可复制的英文 agent 规则块 |
| [AGENTS Templates](skills/agent-workflow-kit/references/agents-templates.md) | 可复制的英文 `AGENTS.md` 模板块 |
| [中文工程规约参考](skills/agent-workflow-kit-zh-cn/references/engineering-references.zh-CN.md) | 可选工程规约参考目录 |
| [Engineering References](skills/agent-workflow-kit/references/engineering-references.md) | 英文工程规约参考目录 |
| [贡献指南](CONTRIBUTING.md) | 贡献与同步要求 |
| [更新日志](CHANGELOG.md) | 项目变更记录 |
| [Level 2 AGENTS 示例](examples/AGENTS.level-2.md) | 可直接复制的标准工作流起点 |
## Agent Skills 与模板
`skills/` 目录放的是面向 agent 的版本。它们采用 Codex-compatible Skill 结构打包，但核心内容是普通 Markdown 和 YAML，因此其他 LLM、coding agent 或 agent harness 也可以直接读取、改写或迁移成自己的项目规则。
这些包是可选的。只想阅读指南或复制 `AGENTS.md` 模板时，直接使用上面的文档入口即可。
| Skill | 用途 |
|---|---|
| `skills/agent-workflow-kit` | 英文 agent Skill 包：评估仓库、风险评分、推荐工作流级别，并在批准后准备项目规则 |
| `skills/agent-workflow-kit-zh-cn` | 中文 agent Skill 包：同样的流程，但面向中文使用场景 |
每个 Skill 包含：
- `SKILL.md`：agent 工作流和安全规则
- `agents/openai.yaml`：显示信息和默认 prompt
- `references/agents-templates*.md`：可复用的 `AGENTS.md` 模板块
- `references/engineering-references*.md`：可选工程规约参考目录
示例 prompt：
```text
使用 $agent-workflow-kit-zh-cn 评估这个仓库，并推荐合适的 AI 工作流级别。
```
```text
Use $agent-workflow-kit to evaluate this repository and recommend the right AI workflow level.
```
## 仓库结构
```text
README.md # 英文项目首页
README.zh-CN.md # 中文项目首页
AGENTS.md # 本仓库的 AI 维护规则
CONTRIBUTING.md # 贡献指南
CHANGELOG.md # 项目变更记录
.gitattributes # GitHub Linguist 元数据
docs/guide.md # 英文完整文档
docs/guide.zh-CN.md # 中文完整文档
examples/AGENTS.level-2.md # 可复制的标准工作流起点
skills/
agent-workflow-kit/ # 英文 agent Skill 包
agent-workflow-kit-zh-cn/ # 中文 agent Skill 包
scripts/check-docs.rb # Markdown、YAML、Skill 和链接校验
.github/workflows/docs-check.yml # GitHub Actions 校验
```
## 校验
发布文档改动前，先运行：
```bash
ruby scripts/check-docs.rb
```
脚本会检查 Markdown 代码块、YAML 语法、Skill 目录结构和公开链接。
## 许可
- 文档正文和 Skill 指令：[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)
- 可复用的 `AGENTS.md` 模板和示例代码块：[CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/)
- 第三方工具和参考遵循各自许可证。