一个仍在迭代中的 AI 工程化脚手架，为 Qoder 生成 Agent/Skill/规则/流程配置，探索让 AI 辅助开发更好用的方式。
📖 学习借鉴了 spec-kit、OpenSpec、mattpocock-skills、Superpowers、gstack 等开源项目。
- 🤔 AK47 解决什么问题？
- ⚡ 快速开始
- 🔧 CLI 命令参考
- 🎁 你的项目会获得什么？
- ✨ 核心机制
- 🧠 设计哲学
- 📚 学习资源
- 👥 自定义配置
- 📂 项目结构
- 🛠️ 开发指南
- 📖 了解更多
- 📮 反馈与建议
- 📋 版本历史
- 📄 许可证
💡 本文中，🖥️ 表示终端命令行操作，🤖 表示在 Qoder 中与 AI 对话完成的操作。
AI 编程助手（如 Qoder、Claude Code、Cursor）越来越强大，但开箱不等于好用。要让 AI 真正理解你的项目规范、遵循开发流程、沉淀开发经验，你需要：
- 🤖 定义专职的 AI Agent 角色（开发者、审查者、架构师……）
- 📋 配置开发 Skills（TDD、系统调试、Code Review……）
- 📜 编写项目规则（禁止臆想 API、1% 规则、禁止过度设计……）
- 🔄 搭建工作流（需求 → 架构 → 计划 → 实现 → 审查 → 归档）
- 🧠 建立知识沉淀机制（ADR、最佳实践、踩坑记录……）
这一切如果从零搭建，需要大量试错和领域知识。AK47 的目标是把这些标准化、模板化，减少从零开始的成本。
核心理念：AK47 的核心是一套 Qoder 配置——包含 Agent（工具）、Skill（能力）、Rules（规范）、流程编排、知识沉淀机制。目标是提供一个可以跑起来的 AI 开发协作起点，而不是终点。
这个项目最初只是为了自己用着顺手，起步时认知有限——该参考什么、融合什么、自己写什么，都是边做边调整。认知升级是个过程，等把几个方向全揉进一套体系之后才发现已经积重难返。如果从零再来，可能会选在 spec-kit 上做插件——框架管规范，自己管定制。不过各有取舍，当前独立维护的形态对个人使用更灵活，做少量调整也可以约束多人协作。目前就是这个形态，还在用，也还在改。
# 一键安装（推荐）
git clone --depth 1 https://github.com/andyxai/AgentKit47-Qoder.git /tmp/ak47-install && \
bash /tmp/ak47-install/scripts/install.sh && \
rm -rf /tmp/ak47-install
# 或静默安装（跳过交互确认）
curl -sSL https://github.com/andyxai/AgentKit47-Qoder/raw/master/scripts/install.sh | bash -s -- --yes安装脚本会自动完成：Node.js 环境检查 → ak47 CLI 安装 → 安装验证（OpenSpec 已内置到模板，无需额外安装）。
本地开发安装：
git clone→npm install→npm run build→npm link
cd your-project
ak47 initak47 init 会扫描你的项目结构（技术栈、现有配置、项目成熟度），推荐并生成 AI 开发环境配置。
在终端中初始化完成后，用 Qoder 打开项目，对 AI 说：
帮我修复一个 Bug # Qoder 会走 L1（轻量级流程）
帮我开发 XXX 功能 # Qoder 会走 L2（中量级流程）
重构 XXX 模块 # Qoder 会走 L3（全量级流程）
🖥️ 也可以用命令行启动：
ak47 change L1/ak47 change L2/ak47 change L3，然后在 Qoder 中继续。
AI 会按照项目的 Agent/Skill/规则配置，尝试引导完成需求定义 → 架构设计 → 计划编写 → TDD 实现 → Code Review → 归档的流程。
详细安装步骤见 安装指南。
| 命令 | 说明 |
|---|---|
ak47 init |
扫描项目结构，推荐并生成 AI Agent/Skill/规则/流程配置 |
ak47 change <L1|L2|L3> |
启动 L1（轻量）/ L2（中量）/ L3（全量）三级变更流程 |
ak47 config <get|set|list|reset> |
查看或修改项目级配置 |
ak47 config-manager |
自定义配置管理（添加 Agent / Skill / 验证类型等） |
ak47 validate |
验证项目配置完整性和一致性 |
ak47 upgrade |
同步项目模板到 CLI 最新版本（SHA256 对比 + 三路 diff） |
ak47 update |
检查并更新 CLI 工具自身到最新版本 |
ak47 doctor |
项目健康体检（环境 / 结构 / 快照 / 升级待办，加 --json 可供 CI 消费） |
运行 ak47 init 🖥️ 后，你的项目会获得以下能力：
产品负责人、架构师、开发者、审查者、流程守护者、知识工程师、配置维护者、脚手架维护者、领域驱动设计——每个 Agent 都有明确的职责边界和工作流程。在 Qoder 中 AI 会尝试调用合适的 Agent 角色。
覆盖需求定义、架构设计、批判性审核、TDD、系统调试、Code Review、领域建模、垂直切片、经验沉淀、知识检索、改进提案与审核等完整开发活动。每个 Skill 附带输入/输出合约说明。在 Qoder 中对 AI 说出需求，AI 会尝试匹配合适的 Skill。
自动注入核心行为规则（禁止臆想 API、禁止过度设计、禁止表面修复、1% 规则等），由 Qoder 平台自动加载到每次 AI 上下文中，无需手动操作。
根据变更复杂度选择流程深度——Bug 修复走轻量级（L1，仅 Code Review），常规功能走中量级（L2，Spec Delta + 实现），系统重构走全量级（L3，完整 Spec 驱动）。在 Qoder 中对 AI 描述任务，流程会尝试自动匹配。
架构决策记录（ADR）、最佳实践、踩坑记录——经验可由 AI 结构化归档到 .ak47/experiences/，供后续检索参考。
AK47 自身行为不符合预期时，可触发改进提案和改进审核两个 Skill：提案方分析根因、区分普适性缺陷与项目特有问题并产出结构化报告；审核方比对 AK47 设计原则和用户项目诉求，给出接纳/修改/暂缓/拒绝/转上游五档裁决及具体修改方案。
可配置性能测试、回归测试、安全扫描等验证类型，支持自动/手动触发。
ak47 validate # 验证项目配置完整性和一致性
ak47 doctor # 项目健康体检
ak47 doctor --json # JSON 输出，可接入 CI/CDcommit-msg 格式检查、敏感信息检测等硬规则由 Git Hook 处理，git commit 时自动触发，不消耗 AI token，无需额外操作。
ak47 config get/set/list/reset # 查看或修改项目配置
ak47 config-manager # 管理自定义 Agent / Skill
ak47 upgrade # 同步模板到最新版本
ak47 update # 更新 CLI 工具自身AK47 在细节上做了不少精巧设计，让 AI 的行为更可控、流程更严谨。详见 精巧设计详解。
| 机制 | 解决的问题 | 怎么做到的 |
|---|---|---|
| 🚦 三层门禁 | AI 跳过关键步骤 | Hook 拦截硬规则 → AGENTS.md 注入规则 → AI 自律响应，层层递进 |
| 🚪 11 个门控点 | AI 擅自推进到下一阶段 | 需求→分类→proposal→design→specs→tasks→审核→审查→提交→验收→分支，每步必须等人明确回复 |
| 🔴 1% 规则 | AI 自判"不需要"而跳过 Skill | 有 1% 可能就调用，跳过需说明原因 → 请示用户 → 获批后才可跳 |
| 🔄 复述确认 | AI 自说自话理解偏差 | 需求盘问后必须用自己的话复述，等用户确认"理解正确"才能继续 |
| 📐 垂直切片 | Spec 互相依赖无法独立交付 | 禁止按技术组件/层次水平切分，必须端到端用户价值路径 |
| 🎚️ 范式感知门控 | 不同变更都走同样重的流程 | L1/L2/L3 三级流程强度，Bug 修复跳过部分门控，架构重构全量执行 |
| 📝 偏离日志 | 跳过规则后无法追溯 | 任何门控跳过必须写 .ak47/deviations.log + 告知用户 + 获批 |
| 🧠 自我改进闭环 | 规则体系逐渐僵化 | 内置改进提案 Skill（诊断） + 改进审核 Skill（裁决），工具自己能进化 |
AK47 不仅是一个工具，也是一套仍在积累中的方法论。在构建 AK47 的过程中，将实践经验整理成了系统化的学习材料。
每个模块都按照 是什么 → 怎么来的 → 为什么有效 → 核心方法 → 对比其他方案 的结构展开，希望能帮你不仅"知道"，还能"理解为什么"和"知道怎么用"。
| 模块 | 解决什么问题 | 阅读时长 |
|---|---|---|
| 01 四大工程纪律 | TDD/DDD/调试SOP/反熵增——四维一体的工程纪律体系 | 15 min |
| 02 系统化调试方法论 | 用结构化方法替代"凭经验猜"，提升排障效率 | 10 min |
| 03 AI 时代的代码重构 | AI 生成代码快但乱，如何把"能跑"变得更好维护 | 12 min |
| 04 Agent 分工决策方法论 | 多 AI Agent 协作时，主/子 Agent 如何分工 | 8 min |
| 05 需求文档双重保障机制 | 四阶段门控 + 独立审核，减少需求返工 | 10 min |
| 06 垂直切分与 Spec 设计 | DDD+OpenSpec+垂直切分三层协同，大需求拆成可交付小Spec | 15 min |
| 12 精巧设计详解 | 三层门禁、门控纪律、1% 规则、复述确认……AK47 中让 AI 不乱来的细节设计 | 12 min |
→ 查看学习中心首页，按你的角色和需求选择阅读路线。
这个项目最初只是为了自己用着顺手。如果现在从零开始，可能会选择在 spec-kit 上开发插件的方式——框架管规范层，自己管定制层。但各有取舍：插件方式更标准化但灵活性受限，当前独立维护的方式对个人使用更灵活，做少量调整也可以用于多人协作，按统一范式约束开发过程，避免过度自由影响协同。目前就是这个形态，还在用，也还在改。SOP 和 TDD 环节还比较薄弱，测试体系也有不少需要优化的地方——这些都是接下来要补的。
所有 Agent/Skill/规则配置在 ak47 init 时一次性生成为静态文件，运行时零渲染开销，可审计、可版本控制。
生成的配置尽量不含项目特定变量——目前的目标是同一个模板适用于大多数项目和语言。但仍在迭代中，适配范围还在验证。
Fork → 修改模板 → 安装，三步把你的工作流沉淀为可复用的标准。
AK47 目前把 Agent、Skill、Hook、Rules 等能力单元都打包在一起，ak47 init 时全量生成到项目。初期这样保证了开箱即用，但随着能力体系越来越厚，有些能力对特定项目可能用不上，整体偏重。
下一步的关键方向是参考 spec-kit 的插件体系，把过重的核心能力拆解为独立插件，按需安装和加载。同时开放用户自定义插件机制，让个人和团队能把自己的工作流沉淀成可复用的插件，而不需要 Fork 整个仓库。
与 spec-kit 的差异：spec-kit 的插件主要围绕 Spec 流转做扩展，AK47 的差异化在于 Hook 体系可以做到更深度的流程介入。Qoder Hook + Git Hook 双轨制可以对 AI 行为做精细的打断和阻断，插件可以直接注册到 Hook 链中参与决策，而不只是提供静态配置或参与 Spec 处理流水线。这一点是 spec-kit 插件模型目前没有覆盖到的。
AK47 在设计中留出了定制空间——你可以根据自己的工作流自由调整。
- Fork 本仓库
- 修改模板：
templates/qoder/下的 Agent、Skill、规则、命令模板按需调整 - 安装：
git clone <你的仓库> && bash scripts/install.sh
install.sh 会自动检测从哪个仓库克隆——Fork 后通常不需要手动改任何地址。
克隆后在 Qoder 中对 AI 说："帮我把 git 地址换成你的仓库地址"，项目内置 skill 会自动替换所有引用。
# 🖥️ 运行时指定仓库
AK47_REPO=https://你的仓库.git curl ... | bash
# 🖥️ 在已有项目中管理自定义配置
ak47 config-manager add-agent --id my-agent --name "我的 Agent" --file path/to/agent.mdAgentKit47/
├── src/
│ ├── cli/commands/ # 8 个 CLI 命令实现
│ ├── core/ # 核心模块
│ │ ├── scanner/ # 项目扫描（技术栈 / 结构 / 平台）
│ │ ├── recommender/ # 智能推荐（规则引擎 + 范式预设）
│ │ ├── generator/ # 模板生成（静态拷贝 + 快照管理）
│ │ ├── orchestrator/ # 流程编排（进度追踪 + 偏离记录）
│ │ ├── validator/ # 配置验证（完整性 / 一致性检查）
│ │ ├── config-manager/ # 自定义配置管理（CRUD + 备份）
│ │ ├── upgrader/ # 升级管理（SHA256 + 三路 diff）
│ │ ├── flows/ # L1/L2/L3 变更流程定义
│ │ └── doctor/ # 项目健康体检
│ ├── types/ # 共享类型定义
│ └── utils/ # 工具函数
├── tests/ # 25 个测试文件
├── templates/ # 能力单元模板（Agent / Skill / 规则 / 命令）
├── docs/ # 设计文档 / 用户指南 / 研究报告
├── scripts/install.sh # 一键安装脚本
├── package.json
└── tsconfig.json
- Node.js >= 20.19.0
- npm >= 10.0.0
- Git >= 2.30.0
npm install # 安装依赖
npm run build # 编译
npm run dev # 监听模式
npm test # 运行测试
npm run test:run # 一次性运行所有测试
npm run lint # 代码检查
npm run format # 代码格式化- TypeScript strict 模式
- ESLint v9 + Prettier 代码规范
- Vitest 测试框架，25 个测试文件
- 模板完整性自动验证（
validate-templates）
| 文档 | 说明 |
|---|---|
| CHANGELOG.md | 版本更新日志 |
| 安装指南 | 详细安装步骤 |
| 系统架构 | 架构设计概览 |
| Agent 设计 | Agent 体系设计文档 |
| 决策记录 | 架构决策记录（ADR） |
| 场景指南 | 典型使用场景详解 |
| 迁移指南 | 从旧版本迁移 |
使用 AK47 的过程中如果有让你不爽的地方，可以在 Qoder 中对 AI 说：
"提交 AK47 改进建议"
AI 会调用改进提案 Skill，帮你把问题和改进方向整理成结构化文本。你只需把生成的文本贴到 GitLab Issues，或邮件到 andyxai@126.com。
每个版本的重要更新摘要，详细记录见 CHANGELOG.md。
| 版本 | 日期 | 重要更新 |
|---|---|---|
| 0.7.11 | 2026-05-20 | 废弃Hook模板清理、TDD文件类型扩展、reviewer权限修复、G1门控增强 |
| 0.7.10 | 2026-05-20 | G1 门控确认标记文件机制，post-prd-draft-check 草稿提醒 Hook，需求确认关键词路由，check_prd 增强，FILE_PREEXISTS Bug 修复 |
| 0.7.9 | 2026-05-20 | OpenSpec 全量内置（移除 CLI 依赖），AK47 元工具项目身份门控，OpenSpec skill 归类修正 |
| 0.7.8 | 2026-05-19 | 版本发布流程加固，模板/本地 AK47 专用配置拆分，Skill 计数修正，新增插件化方向章节 |
| 0.7.7 | 2026-05-15 | version check 三重兜底（+npm registry），init 宪法模板 staged-docs 优化，.gitignore 审计跟踪保留 |
| 0.7.6 | 2026-05-15 | OpenSpec 文档完整性级联检查，init 自动预生成 experiences 索引和 Brief 目录 |
| 0.7.5 | 2026-05-14 | Hook 全面阻断策略：10 个 Qoder Hook + Git pre-commit 全部改为 exit 1 阻断 |
| 0.7.4 | 2026-05-14 | 门控体系 P0 修复：init/upgrade 补缺规则文件，新增 doctor 检查项 + pre-openSpec Hook |
| 0.7.3 | 2026-05-14 | 模板 LLM 友好性优化：去除 emoji 图标和表格，改用纯文本标签 |
| 0.7.2 | 2026-05-14 | TDD 门控增强：前置 Hook + 配置文件类型扩展 + 执行顺序指导 |
| 0.7.1 | 2026-05-14 | 三层门禁架构：增量修改审查门禁 + Brief 门禁，禁止 AI 自审/跳过 Brief |
| 0.7.0 | 2026-05-14 | AGENTS.md 模板重构（规则内联、消除误导性表述），rules 降级为可选增强层 |
| 0.6.9 | 2026-05-14 | 门控 Hook 补齐（3 新 Hook，覆盖 G3-G8/G10），Spec 垂直切片规则，Hook 警告响应规则 |
| 0.6.8 | 2026-05-13 | 同步脚本 URL 替换修复，README 语气收敛 |
| 0.6.7 | 2026-05-13 | 门控规则体系（11 个门控点），自我改进双 Skill 体系（提案+审核），关键 Skill 强制触发规则 |
| 0.6.6 | 2026-05-13 | Spec 审查门禁，移除 openspec skill 目录（改由 openspec init 生成） |
| 0.6.5 | 2026-05-12 | 学习文档语气调整 |
| 0.6.4 | 2026-05-12 | 学习文档外部引用校准，格式统一 |
| 0.6.3 | 2026-05-12 | 新增 release-guide.sh / github-push.sh，安装脚本修复 |
| 0.6.2 | 2026-05-12 | 学习文档章节标题统一，《代码大全2》模块重写 |
| 0.6.1 | 2026-05-12 | README 语气收敛，学习文档全面谦虚化 |
| 0.6.0 | 2026-05-12 | Fork 后一键替换仓库地址，README 全面改版 |
| 0.5.8 | 2026-05-11 | Git 提交规范统一为中文 |
| 0.5.7 | 2026-05-11 | 新项目需求盘问流程自动触发规则 |
| 0.5.6 | 2026-05-11 | init 产出目录结构修复 |
| 0.5.3 | 2026-05-08 | triage-brief / improve-architecture 借鉴 mattpocock-skills，需求-架构-审核三重保障机制 |
| 0.5.2 | 2026-05-07 | Agent/Skill 完全静态化，模板目录彻底清理（删 ~100+ 废弃文件） |
| 0.5.1 | 2026-05-07 | Hook 配置 JSON 化，专注 Qoder 平台 |
| 0.5.0 | 2026-05-07 | 外部平台功能测试开放能力，Config Manager 配置管理器 |
| 0.4.2 | 2026-05-07 | ak47 update 命令，项目配置升级保护机制 |
| 0.4.1 | 2026-05-06 | Git 工作流自动触发规则 |
| 0.4.0 | 2026-05-06 | Git Hooks 体系（零 token 消耗） |
| 0.3.7 | 2026-05-06 | Superpowers 14 个 Skills 完整集成 |
| 0.3.5 | 2026-05-06 | 安装脚本快速参数，多个安装问题修复 |
| 0.3.0 | 2026-05-06 | init 初始化模式选择，平台手动选择 |
| 0.2.0 | 2026-05-03 | 完整复用 Superpowers 能力体系（Skills + Hooks + AGENTS.md） |
| 0.1.0 | 2026-05-03 | 初始版本：Scanner / Recommender / Generator / Orchestrator / Upgrader / Validator 核心模块 |
MIT © andy.zx
AK47 站在以下开源项目的肩膀上：
- spec-kit — Spec 驱动开发框架
- OpenSpec — 规范驱动开发理念
- mattpocock-skills — Skill 设计模式
- Superpowers — AI 编码方法论与 Skill 体系
- gstack — 多平台协同思路
更详细的项目对比分析见 学习中心 · 07 五大项目对比。
感谢这些优秀项目的启发！