Doc管理

1. agents.md

AGENTS.md 是由 OpenAI、Anthropic、Google (Jules)、Cursor 和 Factory 等 AI 领域的领先公司共同推动的一项开源标准。它被定位为“为 AI 代理准备的 README”。

1.1. 建议章节

  • 项目目标和愿景
  • 目录结构说明
  • 技术栈和依赖
  • 编码规范和风格
  • 构建或测试的命令和脚本
  • 测试指导
  • 安全考量
  • 命名约定
  • 错误处理原则
  • 团队特定要求
    best practice
  • https://github.com/openai/codex

1.2. 嵌套

对于大的单体项目，可以在每个软件包中放置一个AGENTS.md 文件。代理会自动读取目录树中最近的文件，每个子项目都可以提供定制的指令。

  • The closest AGENTS.md to the edited file wins
  • explicit user chat prompts override everything

1.3. AGENTS.md vs. README.md 对比表

维度 README.md AGENTS.md
主要受众 人类开发者/用户 AI 编码代理 (AI Coding Agents)
核心目的 项目介绍、安装入门、贡献指南、营销。 提供机器可读的上下文、构建步骤、测试命令和编码规范。
内容重点 易于理解的自然语言，注重宏观概念。 结构化的指令，注重执行命令、架构细节和代码风格。
更新频率 随项目重大更迭而更新。 随技术栈、测试脚本或具体开发任务的细节动态更新。
位置策略 通常位于项目根目录。 支持分层/嵌套。AI 会读取最邻近的 AGENTS.md（如在子包中）。
典型内容 “这是一个 XXX 库”、“安装方法：npm install”。 “运行测试命令：npm test -- --watch”、“使用 React 18 语法”。
文件关联 替代了项目的“门面”。 替代或统一了 .cursorrules、claude.md 等工具专属规则文件。

1.3.1. 为什么要区分这两个文件？

  1. 减少干扰（Noise Reduction）：
    人类开发者不需要在 README.md 中看到极其详尽的、专门给 AI 看的编译脚本或 Lint 检查命令。保持 README 简洁有利于人类快速理解项目。
  2. 机器优化（Machine Optimized）：
    AI 代理需要非常明确、无歧义的指令。AGENTS.md 可以包含具体的命令行片段，AI 能够直接识别并尝试执行这些命令来验证代码（例如：“在提交代码前，请运行此特定命令检查类型”）。
  3. 上下文隔离（Context Isolation）：
    在大规模单体仓库（Monorepos）中，每个子项目可以有自己的 AGENTS.md。当 AI 代理在某个子目录下工作时，它会自动加载最近的规则，从而获得更精准的上下文，减少 Token 浪费并提高准确率。

1.4. 支持情况

支持客户端列表：codex、opencode、cursor、kiro
不支持的客户端列表：antigravity、gemini cli、claude code

ln -s AGENTS.md GEMINI.md
ln -s AGENTS.md CLAUDE.md

2. claude code

2.1. claude.md

claude.md是由anthropic公司提出的，claude code默认加载的上下文

类型 位置 范围 版本控制 典型用途
用户 ~/.claude/CLAUDE.md 所有项目 不共享 个人编码偏好
项目 ./CLAUDE.md或./.claude/CLAUDE.md 当前项目 共享给团队 团队规范
本地 ./CLAUDE.local.md 当前项目（本地） 不共享 项目个人偏好
项目规则 ./.claude/rules/*.md 当前项目 共享给团队 模块、专题规范

2.2. rules最佳时间

  • 保持规则聚焦：每个文件应仅涵盖一个主题（例如：testing.md、api-design.md）。
  • 使用描述性的文件名：文件名应能清晰直观地反映该规则所涵盖的内容。
  • 谨慎使用条件规则：仅在规则确实只适用于特定文件类型时，才在 Frontmatter 中添加路径限制（paths）。
  • 利用子目录进行组织：将相关的规则进行归类分组（例如：frontend/、backend/）。

2.3. 引用

在claude.md中可以使用相对路径、绝对路径，甚至是用户主目录 (~) 的路径来导入额外文件。

# ./CLAUDE.md (项目记忆)

# 导入团队共享的React最佳实践
@/path/to/shared/react-best-practices.md

# 导入我个人的项目特定快捷指令
@~/.claude/my-project-shortcuts.md

技术限制: 最大支持5层递归导入。在Markdown的代码块或行内代码中，@import 不会生效。

2.4. 添加记忆

在会话中输入 /memory 命令，Claude 会在你的系统默认编辑器中打开相关的记忆文件，方便你进行更复杂的编辑、整理和重构。

3. 文档目录组织

.
├── AGENTS.md                  # 🖥项目全局知识，AI Agents使用，可以通过@的方式渐进式披露其他文档
├── README.md                  # 🤵项目简介，给人查阅
├── changelog                  # 🤵归档已完成的变更，基于git diff和agent对话生成的项目修订简介，给人看的
│   └── change_202602.md       
├── rules/                     # 🖥项目开发规范，分类管理（单独文件夹），存放比如数据库表规范、API规范、UI风格倾向等
└── specs                      # 🖥SDD开发目录，详细的架构设计文档，领域知识等
    ├── design.md              # 🖥全量设计，核心架构设计、关键技术选型等。随着业务持续开发，持续更新
    ├── spec.md                # 🖥全量规格，包含项目的功能描述、数据模型等。随着业务持续开发，持续更新
    ├── module/                # 🖥按领域模型划分，存在特定领域模型的design和spec。随着业务持续开发，持续更新
    │   ├── frontend
    │   │   ├── design.md  
    │   │   └── spec.md  
    │   └── backend
    └── changes/               # 🤵记录所有变更
        ├── archive            # 🤵已完成变更
        │   └── 2026-01-31-add-missing-unit-tests-for-metadataparser
        │       ├── design.md
        │       ├── proposal.md
        │       ├── spec.md
        │       └── task.md
        └── fe-xxx             # 🖥进行中的变更
            ├── design.md
            ├── proposal.md
            ├── spec.md
            └── task.md

评论