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

AGENTS.md 构建实践用知识图谱驱动的 AI Agent 上下文体系核心理念传统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连接度最高的核心抽象如TrafficTrack18 条边、useGoToRouteWithAbandon()13 条边揭示代码库的枢纽节点Communities自动聚类的功能社区如 “Portal Redirect” 48 节点、“Map Flow” 32 节点揭示代码的实际边界Surprising Connections跨模块的意外关联暴露隐藏耦合Hyperedges多节点参与的群体关系如 Trust Feedback Cluster、Navigation Control IconsWiki面向新成员的分主题导航文档关键价值让 agent 不仅知道有哪些文件还知道文件之间的真实关系结构。第二层AGENTS.md人工提炼 规则沉淀结构设计项目概述— 一句话说清产品定位技术栈— 列出所有关键依赖及版本核心架构基于知识图谱— 直接引用 graphify 的 God Nodes 和 Communities让 agent 从结构层面理解代码graphify 引用规则— 明确告诉 agent 何时查阅图谱产物Design System 引用规则— 指向 DESIGN.md 并说明触发条件环境搭建— 可直接执行的命令构建与部署— 包含 CI/CD 信息测试— 框架、命令、约定代码规范— ESLint、Prettier、TypeScript、Git 规范项目结构— 目录树 每个目录的职责说明关键编码模式— 这是最有价值的部分⚠️ 陷阱警告如waitUntil只能在 hook 中使用模式示例路由声明、API 调用、状态管理、store.get vs hook已废弃模块迁移指引安全— XSS 防御、验证器等本地调试— 包含上帝模式等实际调试技巧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/graphify src获得graphify-out/全套产物GRAPH_REPORT.md、graph.json、graph.html、wiki/。参考graphifyStep 2提炼核心发现进 AGENTS.md从 GRAPH_REPORT.md 中提取God Nodes → 写入核心架构章节标注每个核心抽象的连接度和作用Top Communities → 按大小排序写入标注节点数和职责域不是照搬报告而是用人类语言重新组织让 agent 能快速建立心智模型Step 3写入编码模式与陷阱这是需要人工沉淀的部分反复踩过的坑如waitUntil滥用导致永久轮询项目特有的模式如store.getvs hook 的选择时机已废弃模块的迁移规则Step 4构建 DESIGN.md结合 graphify wiki 中的components-and-ui.md和实际代码提取视觉语义簇梳理多租户主题机制标注每个设计决策的实现锚点参考VoltAgent/awesome-design-mdStitch: Design MD FormatStep 5设置引用规则在 AGENTS.md 中写入条件触发的查阅规则规则 - 回答架构或代码库相关问题前先阅读 graphify-out/GRAPH_REPORT.md - 如果 graphify-out/wiki/index.md 存在优先通过它导航 - 处理 UI、样式、主题相关任务前先阅读 DESIGN.mdStep 6持续维护新功能开发后运行/graphify src --update增量更新图谱如果基于新 spec 开发功能同步更新 graphify-out/ 中的图谱产物编码陷阱和模式变更时手动更新 AGENTS.md效果这套体系让 AI agent 在处理任务时获得三个层次的上下文结构层graphify知道代码的真实依赖关系和功能边界规则层AGENTS.md知道项目的约定、陷阱和正确做法语义层DESIGN.md wiki知道设计意图和视觉语言相比纯手写的 AGENTS.md这套体系的优势在于graphify 的自动化发现弥补了人类难以穷举的结构关系God Nodes 和 Communities 让 agent 对代码库有鸟瞰能力wiki 提供了按主题组织的深入导航避免 AGENTS.md 过于臃肿DESIGN.md 将视觉决策从代码实现中抽离让 UI 任务有明确的语义入口ReferencesAGENTS.md 标准agents.md 官方网站 — 开放格式规范Linux Foundation 旗下 Agentic AI Foundation 维护GitHub: openai/agents.md — 规范源码仓库AGENTS.md Online 参考手册 — 独立完整参考含模板和示例agents.md 格式概述 (codingagents.md) — 格式对比AGENTS.md vs CLAUDE.md vs .cursorrulesASDLC.io AGENTS.md Specification — 研究驱动的最佳实践指南含 Gloaguen et al. (2026) 研究发现graphifyPyPI: graphifyy — Python 包pip install graphifyyGitHub: safishamsi/graphify — 源码仓库graphify 支持的平台Claude Code、Codex、OpenCode、OpenClaw、Factory Droid