企业官网建设流程全解析

如何给agent-rules-books添加一本新书？从书籍大纲到发布的完整开发者教程

【免费下载链接】agent-rules-booksAGENTS.md rules / skills for AI coding agents: Codex, Cursor & Claude Code. Inspired by Clean Code, Refactoring, DDD, Clean Architecture and DDIA programming books.项目地址: https://gitcode.com/gh_mirrors/ag/agent-rules-books

📚agent-rules-books是一个开源项目，它把《Clean Code》《Refactoring》《Domain-Driven Design》《Clean Architecture》《DDIA》等经典软件工程书籍，提炼成可供 Codex、Cursor、Claude Code 等 AI 编程智能体直接使用的 AGENTS.md 规则文件。本教程带你从零走完"添加一本新书"的完整流程：书籍大纲 → full 规则 → 压缩成 mini/nano → 正式发布，全程照着官方工作文档执行即可。

一、动手前：先理解项目结构

添加新书前，你需要理解仓库里"一本书"到底由哪些文件组成：

三个核心工作文档（本教程全程围绕它们展开）：

• 添书总流程：docs/ADDING_THE_BOOK.md
• 规则压缩流程：_rule-workbench/PROCESS.md
• 发布流程：_rule-workbench/RELEASE.md

💡 目录命名规范：新书目录一律使用小写 kebab-case，例如designing-data-intensive-applications。

二、准备工作：克隆仓库

git clone https://gitcode.com/gh_mirrors/ag/agent-rules-books

克隆完成后浏览一遍已有书籍（比如 clean-code 或 refactoring），感受 full / mini / nano 三种版本的详略差异，这会让你对"压缩到什么程度"有直观标准。

三、第一步：生成完整书籍大纲

按照 docs/ADDING_THE_BOOK.md 的工作流，先让 AI 聊天助手做三件事：

1. 列出完整大纲：每一章、每章内每一节、每节陈述或强烈暗示的每一条操作规则；
2. 反复扩充大纲，直到"没有实质性遗漏"。特别要找回五类容易漏掉的内容：
   • 不可协商的规则（non-negotiable rules）
   • 权衡取舍规则（tradeoff rules）
   • 触发规则（trigger rules）
   • 反模式（anti-patterns）
   • "当不确定时"的处理建议
3. 产出完整full标准 AGENTS.md，而不是随意摘要。要求：
   • 保留书的原有结构和独特视角
   • 义务用MUST、强默认用SHOULD、禁止项用MUST NOT表达
   • 反模式必须显式保留

⚠️ 注意：这一步追求的是"决策等价"（decision-equivalent），不是"句子等价"——目标是让 AI 智能体在做设计、架构、重构、评审决策时表现得像读过这本书。

四、第二步：人工评审，再导入工作台

生成结果不要直接导入，先做一轮人工评审（这一步最能决定新书质量）：

• 重要的本地纪律是否被压扁成了泛泛的建议？
• 模态词强度（MUST / SHOULD / MUST NOT）是否符合书的本意？
• AI 是否编造了书中没有的规则？

评审通过后，把文件移动到_rule-workbench/<book-name>/full.md。参考现有书籍的 traceability.md 可以看到一个成熟书籍最终的工作台结构。

五、第三步：按 PROCESS.md 压缩出 mini 与 nano

让 AI 助手按 _rule-workbench/PROCESS.md 执行压缩工作流。核心要求：

1. 规则分类先行

压缩前先给每条规则分类，常见类别有：

• book-thesis：书的核心矫正性视角（全部保留）
• decision-changing：会改变架构、建模、错误处理等决策（全部保留）
• micro-decision：影响命名、函数形态、参数设计等高频局部选择
• trigger：只在触碰高危区域时激活
• default：智能体默认就会遵守的规则（删除必须给出证据，不能凭感觉）

2. 统一格式

所有规则文件的一级标题必须为：

• 有作者：# OBEY {书名} by {作者名}
• 无作者：# OBEY {来源名}

mini.md和nano.md采用固定结构：何时使用 → 主要矫正偏差 → 决策规则 → 触发规则 → 最终检查清单。

3. 可追溯性

traceability.md 要求每条保留的 mini 规则有M*编号、每条 nano 规则有N*编号，并标注来源章节与full.md行号范围；每条被删掉的规则必须注明去向：covered by Mx、covered by Nx或intentionally lost。

4. 完成前自查

PROCESS.md 末尾有完整验证清单，重点包括：

• ✅ 逐节核对 full 到 mini 的"章节覆盖审查"
• ✅nano.md必须小到可以常驻上下文、独立使用
• ✅mini.md相比nano.md有明确增量价值，且仍能认出这本书的独特观点
• ✅ 每条被删规则都有明确理由（已验证的默认行为、真冗余、过于情境化等）

六、第四步：按 RELEASE.md 正式发布

压缩完成后，按 _rule-workbench/RELEASE.md 执行发布：

1. 校验工作台：该书必须齐备full.md、traceability.md、mini.md、nano.md四个文件，且full.md仍能解析到权威源文件。

2. 更新 README.md：在 Release Matrix 表格中为该书写一行，包含三个版本的行数（wc -l）、规则数、文件大小（wc -c）和文件链接。

3. 拷贝发布文件：

• _rule-workbench/<book>/mini.md→<book>/<book>.mini.md
• _rule-workbench/<book>/nano.md→<book>/<book>.nano.md

4. 发布后验证：README 所有链接可解析、指标与实际文件一致、没有工作台专属文件（如traceability.md）意外泄漏到发布面。

📌 发布规则是确定性的：指标定义在所有书籍间保持统一，保证历史版本可比。

七、进阶：加入兼容性检查

新书加入后，项目还维护着一张书籍两两兼容矩阵。依据 _rule-workbench/CHECK_COMPATIBILITY.md 与 docs/COMPATIBILITY.md，新书需要与现有每本书生成一份对比文件（存放在 docs/compatibility/ 下），给出冲突度、重叠度、互补度评分及 ✅ / ❌ / 🔁 判定，告诉用户"这两本规则能否同时加载给智能体"。

八、常见坑与最佳实践

• ❌跳过人工评审直接导入→ 书的核心观点容易被稀释成通用风格指南；
• ❌把"人类觉得显然"当作"智能体默认会做"→ 删除default规则必须有评测或错误案例证据；
• ❌H1 标题随意写→ 全部文件必须统一为# OBEY ...格式，不加版本标签；
• ✅ 发现反复出现的压缩失误时，先改 PROCESS.md 再重跑该书，而不是手工微调单个文件；
• ✅ 压缩忠于原书，不要顺手把其他书的"最佳实践"混进来。

总结与延伸阅读

回顾整个流程：大纲 → full 生成与评审 → 工作台导入 → PROCESS 压缩 → RELEASE 发布，七步全部有官方文档兜底，照做即可完成一本书从 0 到 1 的收录。

想深入了解，推荐继续阅读：

• 使用方法与技能模式：docs/USAGE.md
• 书籍兼容性总表：docs/COMPATIBILITY.md
• 书籍提取工作流原文：docs/ADDING_THE_BOOK.md
• 发布历史：CHANGELOG.md

【免费下载链接】agent-rules-booksAGENTS.md rules / skills for AI coding agents: Codex, Cursor & Claude Code. Inspired by Clean Code, Refactoring, DDD, Clean Architecture and DDIA programming books.项目地址: https://gitcode.com/gh_mirrors/ag/agent-rules-books