Skip to content
Back to search

agentic-engineering-framework

开箱即用、可按项目定制的 AI Coding Agent Skills 框架:提供通用 Workflow、可扩展的项目私有知识、自我学习闭环和问题排查能力,适配任意技术栈和工程场景。兼容主流 Coding Agent。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/davidyichengwei--agentic-engineering-framework/badge.svg)](/listings/davidyichengwei--agentic-engineering-framework)

HTML

<a href="/listings/davidyichengwei--agentic-engineering-framework"><img src="/api/listings/davidyichengwei--agentic-engineering-framework/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 274 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Agentic Engineering Framework
  2. 基于 Skill 的模块化 Agentic Engineering 框架——将工程纪律与 AI 能力系统性结合,覆盖从需求澄清到代码审查的完整研发流程,并通过反馈闭环自动沉淀团队工程经验。
  3. > 关于 Agentic Engineering 方法论的完整推导,参见 [《从第一性原理思考 Agentic Engineering》](./agentic_engineering.md)。本框架是该文章的实践落地。
  4. ## 快速开始
  5. ### 1. 克隆仓库
  6. ```bash
  7. git clone https://github.com/davidYichengWei/agentic-engineering-framework.git
  8. cd agentic-engineering-framework
  9. ```
  10. ### 2. 复制到 Agent 配置目录
  11. 不同 agent 使用不同的配置目录,将三个文件夹复制到对应位置:
  12. ```bash
  13. # Claude Code
  14. cp -R agents skills commands ~/.claude/
  15. # Codex CLI
  16. cp -R agents skills commands ~/.codex/
  17. # CodeBuddy
  18. cp -R agents skills commands ~/.codebuddy/
  19. # 其他支持类似 skill/agent 结构的 agent
  20. cp -R agents skills commands <your-agent-config-dir>/
  21. ```
  22. ### 3. 验证
  23. 启动与 agent 的对话,尝试一个 command:
  24. ```
  25. /code-review
  26. ```
  27. Agent 应该会加载 `workflow-code-review` skill 并按照定义的审查流程执行。
  28. ## 推荐工作流
  29. 框架会根据上下文自动触发 skill,但**主动通过 command 调用更可靠**。完整的功能开发流程推荐顺序:
  30. ```
  31. /requirements-clarification → 澄清需求,生成 spec.md(AI 作为引导者)
  32. ↓
  33. /system-design → 设计方案,填写 spec.md 的设计章节(AI 作为协作者)
  34. ↓
  35. /code-generation → 实现代码,自动加载编码规范,逐任务推进(AI 作为执行者)
  36. ↓
  37. /test-generation → 基于 spec 和实现生成测试
  38. ↓
  39. /code-review → 对照 spec 和规范审查变更
  40. ```
  41. AI 在不同阶段扮演不同角色:需求阶段是**引导者**(通过结构化提问帮你将模糊意图显式化)、设计阶段是**协作者**(分析权衡、提出替代方案)、编码阶段是**执行者**(在明确规格下自主实现)。每个阶段产出的结构化文档自然成为下一阶段的高质量上下文,形成正向循环。
  42. **流程的严格程度与任务的风险成正比**——不必每次都走完整流程:
  43. - **小 bug 修复?** → 直接 `/code-generation`(它会评估复杂度,简单改动可跳过 spec)
  44. - **线上故障?** → 直接 `/troubleshooting`
  45. - **优化热点路径?** → 直接 `/performance-optimization`
  46. - **审查一个 diff?** → 直接 `/code-review`
  47. ## 经验沉淀(Self-Refinement)
  48. AI agent 没有跨会话记忆——这一轮对话中纠正过的错误,下一轮可能原样重现。Self-Refinement 机制通过将纠错经验转化为持久化的 Skills 来解决这个问题。
  49. **两种触发方式:**
  50. - **自动触发**:当你在协作中纠正了 AI 的错误,AI 会在完成纠正后,在回复末尾给出轻量的经验沉淀建议(不超过 3 条),经你确认后执行。
  51. - **手动触发(`/reflect`)**:主动发起当前对话的全面回顾。AI 会识别对话中所有被纠正的错误模式,对每个错误执行完整的诊断闭环:识别错误模式 → 诊断根因 → 检索现有知识 → 生成建议 → 用户确认 → 执行更新。
  52. **典型场景:**
  53. | 你纠正了什么 | 沉淀到哪里 |
  54. |------------|-----------|
  55. | "变量命名应该用 snake_case" | `std-*` 编码规范 Skill |
  56. | "这个模块的锁应该用 bthread mutex" | `std-*` 模块规范 Skill |
  57. | "不要跳过 spec 直接写代码" | `workflow-code-generation` Skill |
  58. | "错误处理要用 Status 而不是返回 -1" | `bp-coding-best-practices` Skill |
  59. 这使得团队的工程经验可以**从对话中自然生长**,而非依赖人工维护文档。每次纠正都是一次改进框架的机会。
  60. ## 如何扩展
  61. Best Practices 和 Standards 是框架中**最需要按项目定制**的部分。框架不规定具体内容——它规定的是**知识应该以什么形式存在、在什么时机被加载、如何被演进**。
  62. ### 添加语言规范
  63. 创建新的 `std-*` skill:
  64. ```
  65. skills/
  66. └── std-python/
  67. ├── SKILL.md # 编码规范概览
  68. └── reference/
  69. └── style-guide.md # 详细规则
  70. ```
  71. 然后在需要它的 workflow skill 中注册。例如在 `workflow-code-generation/SKILL.md` 的「按需加载」表格中添加:
  72. ```markdown
  73. | `std-python` Skill | 文件为 `.py` |
  74. ```
  75. ### 添加最佳实践
  76. 创建新的 `bp-*` skill:
  77. ```
  78. skills/
  79. └── bp-security/
  80. ├── SKILL.md
  81. └── reference/
  82. └── owasp-top-10.md
  83. ```
  84. 然后在对应的 workflow skill 中引用。常见的集成点:
  85. | 集成点 | 何时添加 |
  86. |--------|----------|
  87. | `workflow-code-generation` → 步骤 3(加载规范) | 编码时需要遵循的规范 |
  88. | `workflow-code-review/code-reviewer.md` → 审查维度 | Review 时需要检查的维度 |
  89. | `workflow-test-generation` → 测试策略 | 需要考虑的测试类别 |
  90. | `troubleshooting` → 模块专项指南 | 特定领域的排查知识 |
  91. ### 添加排查案例
  92. 将案例文件放入 troubleshooting skill 的 reference 目录:
  93. ```
  94. skills/
  95. └── troubleshooting/
  96. └── reference/
  97. └── cases/
  98. └── <module>/
  99. └── <case-name>.md
  100. ```
  101. ### 编写新 Skill
  102. 使用 `/skill-authoring` 获取编写指导。核心原则:
  103. - **只写 AI 不知道的内容** — 项目特定信息,而非通用知识
  104. - **SKILL.md 不超过 500 行** — 详细内容放在 `reference/` 文件中
  105. - **引用深度只有一层** — 不要出现 A→B→C 链式引用
  106. 完整的编写指南见 `skills/bp-skill-authoring/`。
  107. ## 解决什么问题
  108. AI 编码 agent 能力很强,但缺乏纪律性。没有明确的流程约束时,它们往往会:
  109. - 跳过需求澄清,直接写代码——在意图转化链的源头就引入损耗,越往下游代价越大
  110. - 会话中途忘记编码规范——LLM 的工作记忆有限且易失,关键上下文随对话膨胀而被稀释
  111. - 跨会话输出质量不一致——LLM 没有持久记忆,上一次会话中学到的教训下一次全部丢失
  112. - 生成速度远超审查速度——生成成本骤降但验证成本未降,认知过载成为新瓶颈
  113. 本框架通过将工程最佳实践编码为 agent 可读的 Skill 文件来系统性地解决这些问题:
  114. | 核心实践 | 解决什么 | 框架中的体现 |
  115. |---------|---------|------------|
  116. | **Context Engineering** | 上下文质量决定输出质量上限 | Spec-First、渐进式披露、按需加载 |
  117. | **AI 全链条参与** | 源头损耗传播最远、修复代价最高 | 从需求澄清到代码审查的完整 Workflow |
  118. | **小任务推进、多层次验证** | 控制 AI 概率性输出的错误累积 | 任务拆解 + 逐步审查 + 多维度验证 |
  119. | **Knowledge as Code** | 团队私有知识是 AI 的知识盲区 | Best Practices / Standards 编码为 Skill |
  120. | **Error-Driven Refinement** | LLM 无跨会话记忆,纠错经验易丢失 | Self-Refinement 自动/手动反馈闭环 |
  121. ## 适合谁使用
  122. - **个人开发者**:使用 AI 编码 agent(Claude Code、Codex CLI、CodeBuddy、Cursor、Windsurf 等),希望获得更可靠、结构化的输出。
  123. - **工程团队**:希望标准化 AI agent 在团队代码库中的工作方式——将资深工程师的设计原则和编码规范编码为 Skill,通过 AI 分发给每个成员,拉平团队内部的能力差异。
  124. - **Skill 作者**:希望基于成熟的结构和最佳实践来编写自定义 agent skill。
  125. ## 框架架构
  126. ```
  127. ┌──────────────┐
  128. │ 用户请求 │
  129. └──────┬───────┘
  130. │
  131. ▼
  132. ┌─────────────────────────────────────────────────────────────────────────────────────┐
  133. │ Workflow Skills (主入口) │
  134. │ │
  135. │ 需求澄清 ──▶ 系统设计 ──▶ 代码生成 ──▶ 测试生成 ──▶ 代码评审 │
  136. │ │
  137. └─────────────────────────────────────────┬───────────────────────────────────────────┘
  138. │
  139. 按需调用
  140. │
  141. ┌───────────────────┼───────────────────┐
  142. ▼ ▼ ▼
  143. ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
  144. │ Best Practices │ │ Standards │ │ Docs │
  145. │ (通用知识) │ │ (项目私有知识) │ │ (Docs as Code) │
  146. │ │ │ │ │ │
  147. │ 架构设计 │ │ 语言规范 │ │ spec.md │
  148. │ 编码实践 │ │ 模块规范 │ │ 设计文档 │
  149. │ 性能优化 │ │ 测试规范 │ │ 架构决策记录 │
  150. │ 分布式系统 │ │ ... │ │ ... │
  151. │ ... │ │ │ │ │
  152. └──────────────────┘ └──────────────────┘ └──────────────────┘
  153. ┌──────────────────────────────────────┐ ┌──────────────────────────────────────────┐
  154. │ Troubleshooting (独立入口) │ │ Self-Refinement (反馈闭环) │
  155. │ │ │ │
  156. │ 编译错误 / 运行异常 / │ │ 自迭代 Skill (自动触发) │
  157. │ 流水线报错 / 现网告警 │ │ + 经验沉淀 Command (手动触发) │
  158. └──────────────────────────────────────┘ └──────────────────────────────────────────┘
  159. ```
  160. 框架分为三层文件结构,对应不同的加载时机:
  161. ```
  162. agents/ → Subagent 定义(如代码审查中的专项 reviewer)
  163. commands/ → 用户触发的入口(如 /code-generation、/troubleshooting)
  164. skills/ → 详细的工作流和知识定义(按需加载,不消耗常驻上下文)
  165. ```
  166. ### Agents
  167. Agent 是可独立执行子任务的专项角色,由 workflow skill 按需调度:
  168. | Agent | 职责 |
  169. |-------|------|
  170. | `codebase-researcher` | 深度代码库探索,追踪调用链、分析模块依赖 |
  171. | `performance-reviewer` | 性能专项审查:热路径、内存、锁竞争、算法复杂度 |
  172. | `robustness-reviewer` | 健壮性专项审查:边界条件、错误处理、资源泄漏 |
  173. | `spec-compliance-reviewer` | Spec 符合度审查:验证实现是否匹配设计 |
  174. | `standards-reviewer` | 编码规范审查:命名、风格、宏使用、锁原语 |
  175. | `magical-prompt-reviewer` | 契约与信任链审查:变更引入的契约破坏和信任链断裂 |
  176. | `review-critic` | 对抗性验证:对候选 finding 寻找反证,驳回误报 |
  177. ### Commands(用户触发)
  178. Command 是加载对应 skill 的快捷方式:
  179. | Command | 加载的 Skill |
  180. |---------|-------------|
  181. | `/requirements-clarification` | `workflow-requirements-clarification` |
  182. | `/system-design` | `workflow-system-design` |
  183. | `/code-generation` | `workflow-code-generation` |
  184. | `/test-generation` | `workflow-test-generation` |
  185. | `/code-review` | `workflow-code-review` |
  186. | `/troubleshooting` | `troubleshooting` |
  187. | `/performance-optimization` | `bp-performance-optimization` |
  188. | `/reflect` | `self-refinement` |
  189. | `/skill-authoring` | `bp-skill-authoring` |
  190. ### Skills
  191. Skill 是框架的核心载体——模块化、按需加载、可组合。大量 Skills 不会拖垮上下文窗口,因为框架采用三层加载机制:
  192. | 层级 | 内容 | 加载时机 | Token 成本 |
  193. |------|------|---------|-----------|
  194. | **L1: Metadata** | YAML frontmatter(name, description) | Agent 启动时 | ~100/Skill |
  195. | **L2: Instructions** | SKILL.md 主体指令 | Skill 被触发时 | < 5k |
  196. | **L3: Resources** | reference/(参考文档)、scripts/(脚本) | 被显式引用时 | 按需 |
  197. Skill 分为四类:
  198. | 前缀 | 类型 | 角色 | 示例 |
  199. |------|------|------|------|
  200. | `workflow-*` | 工作流 | 端到端流程控制,是主入口 | `workflow-code-generation`、`workflow-code-review` |
  201. | `bp-*` | 最佳实践 | 通用工程知识,由工作流按需加载 | `bp-coding-best-practices`、`bp-distributed-systems` |
  202. | `std-*` | 编码规范 | 语言/团队特定的编码标准 | `std-cpp`、`std-go` |
  203. | *(其他)* | 工具型 | 独立能力 | `troubleshooting`、`self-refinement` |

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.