Agent Workflow Kit

面向 Codex、Claude、Gemini 等 CLI Agent 的项目级工作流脚手架。

它会在任意项目中生成一套可迁移的 .agents 工作流，自动绑定当前项目，并初始化空的知识库骨架。

快速开始

npx @yangxy6/agents-workflow-kit init

指定项目名：

npx @yangxy6/agents-workflow-kit init --project-name my-app

安装到其他目录：

npx @yangxy6/agents-workflow-kit init --target ./my-app

命令

• agent-workflow init：生成 .agents 和根入口桥接文件
• agent-workflow audit：检查生成后的工作流文件是否完整
• agent-workflow doctor：检查本地环境和 .agents/config.json

会生成什么

• .agents/：AI 工作流规则、角色、工具、治理规则和空知识库
• AGENTS.md、CLAUDE.md、GEMINI.md：项目根入口桥接文件
• .agents/config.json：项目绑定信息和可选 skills 配置

如果目标项目里已经存在这些文件，会先备份到 .agents-backup/<timestamp>/，再写入新版本。

工作流是什么

Agent Workflow Kit 生成的是一套“项目内 AI 协作工作流”，核心目标是让 CLI Agent 在任意代码仓库里都按同一套方式工作：

• 先路由任务，而不是直接展开所有上下文
• 默认读取最小上下文，必要时再扩容
• 明确能不能写代码、涉及哪个项目、该走哪个 workflow
• 复杂任务保留计划、验证、知识库留存和委派边界
• 人类文档和 AI 执行规则分开维护

AI 进入项目后，会从根入口文件进入 .agents，再读取核心规则，最终由 router.md 输出统一路由契约：

workflow + mode + target_projects + no_write

路由参数

| 参数 | 含义 | 常见值 | | --- | --- | --- | | workflow | 任务类型和执行流程 | feature、bugfix、review、scan、delivery | | mode | 上下文加载和角色链强度 | light、extended、review | | target_projects | 本次任务影响的项目 | 默认是安装时绑定的项目名 | | no_write | 是否禁止修改业务代码 | false、true |

scan 默认 no_write=true，但允许写扫描报告到 .agents/context/Project/*/docs/code-scan/。

Workflows

| workflow | 适用场景 | 默认行为 | | --- | --- | --- | | feature | 新功能、页面能力增强、交互调整 | 默认可改代码，走最小实现和验证 | | bugfix | 明确异常、回归、报错修复 | 聚焦复现、根因、最小修复和回归验证 | | review | 只做代码评审 | 默认 no_write=true，先输出风险和问题 | | scan | 架构、性能、安全、工程基建扫描 | 默认不改业务代码，可输出报告 | | delivery | 从 PRD/需求到计划、实现、测试用例和页面验证 | 默认扩展模式，强调文档和验证闭环 | | refactor | 不改变外部行为的结构调整 | 默认并入 feature |

Modes

| mode | 适用场景 | 加载策略 | | --- | --- | --- | | light | 单点 feature、bugfix、小范围 UI/文案/局部逻辑 | 只读 router、planner/coder/qa、目标 workflow、必要 tools 和项目上下文 | | extended | 公共模块、长链路、多页面、多项目、构建发布、较高风险 | 在 light 基础上补 architect、reviewer、devops、orchestrator 和必要上下文 | | review | 纯评审任务 | 只读 planner、reviewer、qa 和 review workflow |

delivery 和 scan 都会使用 extended 级别的上下文强度。

角色链

默认链路：

planner -> coder -> qa

复杂任务扩展为：

planner -> architect -> coder -> qa -> reviewer -> devops

角色含义：

• planner：拆解步骤、验收标准和测试范围
• architect：评估架构、公共模块、兼容性和影响面
• coder：完成最小必要实现
• qa：执行验证并记录结果，不改代码
• reviewer：复查风险、回归和遗漏
• devops：处理构建、发布、CI 和环境相关风险

上下文加载策略

默认遵循“少读、读准”：

• light 不默认读取历史知识库正文
• docs/ 是给人看的说明层，不默认进入 AI 执行主链
• PROJECT_CONTEXT.md 只放项目核心事实
• 更长的项目说明应放到 .agents/context/Project/<project>/docs/
• 文档治理规则只在需要留档时读取

知识库

安装后会初始化空知识库：

.agents/context/Project/<project>/
.agents/context/Personal/

推荐规则：

• 项目事实写入 PROJECT_CONTEXT.md
• 项目级专题写入 docs/
• 需求级正文写入模块/需求目录
• 新增文档后同步更新最近的 目录.md
• 模块目录先登记到 module-registry.tsv

Skills

默认不绑定任何固定 skill。你可以在 .agents/config.json 里配置自己的 skills。

{
  "skills": {
    "review": [],
    "delivery": [],
    "scan": []
  }
}

空数组表示不启用 skills。配置了 skill 但当前环境不可用时，工作流应降级为普通流程并记录限制。

典型任务映射

| 用户请求 | 推荐路由 | | --- | --- | | “修复按钮点击没反应” | workflow=bugfix、mode=light | | “新增设置页的一个开关” | workflow=feature、mode=light | | “评审当前 diff” | workflow=review、mode=review、no_write=true | | “扫描项目性能问题并输出报告” | workflow=scan、mode=extended、no_write=true | | “根据 PRD 完成需求文档、开发计划、测试用例和实现验证” | workflow=delivery、mode=extended |

English

Agent Workflow Kit is project-local workflow scaffolding for Codex, Claude, Gemini, and similar CLI agents.

It creates a portable .agents workflow, binds it to the current project, and initializes an empty retained knowledge base.

Quick start:

npx @yangxy6/agents-workflow-kit init

Commands:

• agent-workflow init: generate .agents and root bridge files
• agent-workflow audit: validate generated workflow files
• agent-workflow doctor: check local environment and config