Awesome 15docs

Appearance

On this page
字数:1.7k 字
预计:5 分钟
阅读量:

AGENTS.md 构建实践：用知识图谱驱动的 AI Agent 上下文体系 ​

作者:winches
更新于:2 分钟前

核心理念 ​

传统 README.md 面向人类，解释"这个项目是什么"。AGENTS.md 面向 AI coding agent，回答"如何在这个项目里正确工作"。但仅靠手写文档覆盖面有限——大型代码库的架构关系、隐藏耦合、核心抽象，人很难穷举。

本实践的核心创新：先用 graphify 自动化提取代码库的结构知识，再将关键发现沉淀进 AGENTS.md，形成"自动化发现 + 人工提炼"的闭环。

体系架构 ​

整套体系由四层文档构成，各有分工：

仓库根目录/
├── AGENTS.md              ← 核心：Agent 工作指南（引用 graphify 发现）
├── DESIGN.md              ← 设计系统语义描述（UI/视觉/主题）
├── graphify-out/          ← 自动生成的知识图谱产物
│   ├── GRAPH_REPORT.md    ← 审计报告（God Nodes、Communities、Surprising Connections）
│   ├── graph.json         ← 原始图数据
│   ├── graph.html         ← 可视化交互图
│   └── wiki/              ← 自动生成的分主题 wiki
│       ├── index.md
│       ├── architecture-overview.md
│       ├── pages-and-flows.md
│       ├── state-and-data.md
│       ├── components-and-ui.md
│       ├── platform-and-infra.md
│       └── glossary-and-hotspots.md
└── docs/superpowers/      ← AI agent 产出的 spec 和计划
    ├── specs/             ← 设计规格文档
    └── plans/             ← 分步实现计划

第一层：graphify 知识图谱（自动化发现） ​

做什么 ​

对 src/ 执行 /graphify，通过 AST 解析 + 语义提取构建代码知识图谱。

产出 ​

  • God Nodes：连接度最高的核心抽象（如 TrafficTrack 18 条边、useGoToRouteWithAbandon() 13 条边），揭示代码库的"枢纽节点"
  • Communities：自动聚类的功能社区（如 "Portal Redirect" 48 节点、"Map Flow" 32 节点），揭示代码的实际边界
  • Surprising Connections：跨模块的意外关联，暴露隐藏耦合
  • Hyperedges：多节点参与的群体关系（如 Trust Feedback Cluster、Navigation Control Icons）
  • Wiki：面向新成员的分主题导航文档

关键价值 ​

让 agent 不仅知道"有哪些文件"，还知道"文件之间的真实关系结构"。

第二层：AGENTS.md（人工提炼 + 规则沉淀） ​

结构设计 ​

  1. 项目概述 — 一句话说清产品定位
  2. 技术栈 — 列出所有关键依赖及版本
  3. 核心架构（基于知识图谱） — 直接引用 graphify 的 God Nodes 和 Communities，让 agent 从结构层面理解代码
  4. graphify 引用规则 — 明确告诉 agent 何时查阅图谱产物
  5. Design System 引用规则 — 指向 DESIGN.md 并说明触发条件
  6. 环境搭建 — 可直接执行的命令
  7. 构建与部署 — 包含 CI/CD 信息
  8. 测试 — 框架、命令、约定
  9. 代码规范 — ESLint、Prettier、TypeScript、Git 规范
  10. 项目结构 — 目录树 + 每个目录的职责说明
  11. 关键编码模式 — 这是最有价值的部分：
    • ⚠️ 陷阱警告（如 waitUntil 只能在 hook 中使用）
    • 模式示例（路由声明、API 调用、状态管理、store.get vs hook）
    • 已废弃模块迁移指引
  12. 安全 — XSS 防御、验证器等
  13. 本地调试 — 包含"上帝模式"等实际调试技巧
  14. PR 指南 — 分支命名、提交规范

关键写法原则 ​

  • 每条规则都是可执行的指令，不是描述性文字
  • 代码示例用 ✅/❌ 对比，让 agent 直接判断对错
  • 引用图谱时用条件触发（"回答架构问题前，先阅读 graphify-out/GRAPH_REPORT.md"）

第三层：DESIGN.md（设计系统语义） ​

解决的问题 ​

Agent 在做 UI 相关工作时，需要理解的不只是"用什么组件"，而是"为什么这么设计"。

独特设计 ​

  • 不是组件 API 文档，而是设计意图的语义描述
  • 每个 section 末尾都有"实现锚点"，直接指向代码文件
  • 将视觉决策与 graphify 社区关联
  • 覆盖：视觉氛围、色彩体系、排版规则、组件样式、布局原则、面向 Agent 的仓库映射

第四层：docs/superpowers/（AI 协作产物） ​

  • specs/ — brainstorming skill 产出的设计规格
  • plans/ — writing-plans skill 产出的实现计划

形成"设计 → 规划 → 实现"的完整 AI 协作链路。

构建流程 ​

Step 1：运行 graphify ​

bash
/graphify src

获得 graphify-out/ 全套产物：GRAPH_REPORT.md、graph.json、graph.html、wiki/。

参考：graphify

Step 2：提炼核心发现进 AGENTS.md ​

从 GRAPH_REPORT.md 中提取：

  • God Nodes → 写入"核心架构"章节，标注每个核心抽象的连接度和作用
  • Top Communities → 按大小排序写入，标注节点数和职责域
  • 不是照搬报告，而是用人类语言重新组织，让 agent 能快速建立心智模型

Step 3：写入编码模式与陷阱 ​

这是需要人工沉淀的部分：

  • 反复踩过的坑（如 waitUntil 滥用导致永久轮询）
  • 项目特有的模式（如 store.get vs hook 的选择时机）
  • 已废弃模块的迁移规则

Step 4：构建 DESIGN.md ​

结合 graphify wiki 中的 components-and-ui.md 和实际代码：

  • 提取视觉语义簇
  • 梳理多租户主题机制
  • 标注每个设计决策的实现锚点

参考：VoltAgent/awesome-design-mdStitch: Design MD Format

Step 5：设置引用规则 ​

在 AGENTS.md 中写入条件触发的查阅规则：

markdown
规则：
- 回答架构或代码库相关问题前，先阅读 graphify-out/GRAPH_REPORT.md
- 如果 graphify-out/wiki/index.md 存在，优先通过它导航
- 处理 UI、样式、主题相关任务前，先阅读 DESIGN.md

Step 6：持续维护 ​

  • 新功能开发后，运行 /graphify src --update 增量更新图谱
  • 如果基于新 spec 开发功能，同步更新 graphify-out/ 中的图谱产物
  • 编码陷阱和模式变更时，手动更新 AGENTS.md

效果 ​

这套体系让 AI agent 在处理任务时获得三个层次的上下文：

  1. 结构层（graphify）：知道代码的真实依赖关系和功能边界
  2. 规则层（AGENTS.md）：知道项目的约定、陷阱和正确做法
  3. 语义层（DESIGN.md + wiki）：知道设计意图和视觉语言

相比纯手写的 AGENTS.md，这套体系的优势在于：

  • graphify 的自动化发现弥补了人类难以穷举的结构关系
  • God Nodes 和 Communities 让 agent 对代码库有"鸟瞰"能力
  • wiki 提供了按主题组织的深入导航，避免 AGENTS.md 过于臃肿
  • DESIGN.md 将视觉决策从代码实现中抽离，让 UI 任务有明确的语义入口

References ​

AGENTS.md 标准 ​

graphify ​

Made with ❤️

MIT License © 2023 winchesHe