project-guidelines-example

project-guidelines-example 快速入门

一份能直接拿来用的 AGENTS.md / CLAUDE.md 模板,让 AI 立刻”读懂”你的项目规范。

这是什么?解决什么问题?

新人(包括 AI Agent)接手一个项目时最大的痛点是:不知道项目用什么语言、什么框架、什么命名风格、什么测试约定、什么部署流程。每次都要问老员工,或者读一堆零散的 wiki 页。
project-guidelines-example 是 affaan-m/everything-claude-code 仓库里提供的”完整项目规范 Skill 模板”。它是一份结构化文档示例,涵盖:项目元信息(名称/技术栈/版本)、目录结构、命名约定、代码风格、Git 提交规范、测试约定、部署流程、紧急联系人。
把它放到项目根目录的 AGENTS.md 或 CLAUDE.md,AI Agent(Claude Code、Cursor、Aider、Cody 等)在进入项目时自动读取,立刻了解”该用什么风格写代码”、“测试如何跑”、“提交信息怎么写”。
这相当于给 AI Agent 写了一份”入职手册”,大幅减少每次都要重复交代背景的繁琐。
适合:新项目立项、需要快速规范 AI 工作流的团队、想让 AI 协作体验更顺滑的技术 Lead。

准备工作

1. Git 项目:已初始化或新建
   
2. Claude Code / Cursor / 任何读 AGENTS.md / CLAUDE.md 的 AI 客户端
   
3. 可选:团队 wiki 链接(供 AI 进一步查背景)
   
4. 可选:markdownlint 校验模板格式
   

3 步快速上手

第 1 步:安装 Skill

npx skills add affaan-m/everything-claude-code --skill project-guidelines-example<br>
```<br>
仓库:https://github.com/affaan-m/everything-claude-code<br>
### 第 2 步:验证 Skill<br>
向 AI 询问:<br>
```<br>
用 project-guidelines-example Skill,展示一个完整的 AGENTS.md 模板包含哪些章节<br>
```<br>
如果 AI 列出"项目元信息、目录结构、命名约定、测试、部署"等,说明 Skill 加载成功。<br>
### 第 3 步:把模板落到项目<br>
```<br>
用 project-guidelines-example Skill 帮我生成项目的 AGENTS.md,<br>
我的项目是 React + TypeScript + Vite,使用 pnpm,测试用 Vitest<br>
```<br>
AI 会输出定制化的 `AGENTS.md`,直接放到项目根目录,提交到 Git 即可。<br>
## 常见踩坑<br>
1. **模板太通用**:复制官方模板后没改项目特定信息(技术栈、命令),AI 看到的是"hello world 项目"风格,实际项目是 monorepo,产生混淆。<br>
2. **AGENTS.md 和 CLAUDE.md 混用**:Claude Code 默认读 `CLAUDE.md`,但 `agents.md` 规范统一用 `AGENTS.md`。要在项目里只放一个,避免冲突。<br>
3. **规范过期不维护**:写完 1 年没更新,实际项目已经从 React 迁到 Next.js,AGENTS.md 还是 React 时代的内容,AI 按错的规范写代码。<br>
4. **过度细节**:把每个 API 端点都写进 AGENTS.md,文件长达 5000 行,AI 读上下文要花大量 token。只写"原则 + 关键命令",细节放链接到 wiki。<br>
5. **和 .cursorrules / README 重复**:同样内容放 3 个文件,维护时容易漏改。建议 AGENTS.md 是主源,其他文件引用它。<br>
6. **团队成员不读**:AGENTS.md 写得很详细但没人看(包括人类成员),靠"口口相传",新人入职依然靠问。可以在 PR 模板里强制要求"新员工 review 过 AGENTS.md"。<br>
## 初级用法<br>
1. **新项目立项**:从模板复制一份到 `AGENTS.md`,改技术栈、命令、命名风格,提交第一个 commit。<br>
2. **重构期**:把"重构期间的特别约定"(如"不在此 PR 改 UI 文本")写在 AGENTS.md 的"当前临时约定"段。<br>
3. **多项目团队**:每个项目根目录一份 AGENTS.md,内容只针对当前项目,跨项目约定放团队 wiki。<br>
## 高级玩法<br>
1. **自动生成**:写一个脚本,根据 `package.json` + `tsconfig.json` + 目录结构自动生成 AGENTS.md,降低维护成本。<br>
2. **版本化规范**:AGENTS.md 加 changelog 段,每次重大变更记录,方便回溯"为什么改了约定"。<br>
3. **AI 辅助维护**:让 AI 定期读 AGENTS.md vs 实际项目状态,提示"以下条目已过期,建议更新"。<br>
## 小技巧<br>
- AGENTS.md 控制在 100-200 行,太短信息不全,太长没人看。<br>
- 用清晰的章节标题(## / ###),AI 解析时定位更快。<br>
- 关键命令用代码块(````bash ... ````),AI 可直接执行。<br>
- 链接到外部资源用完整 URL,不要用相对路径,跨平台(IDE / Web)都能跳。<br>
- 在 README.md 加一句"请阅读 AGENTS.md 了解项目规范",把规范和项目介绍关联。<br>
- 约定变更时,PR 标题用 `docs(agents): <change>`,显眼且便于追溯。<br>
- AI 写完代码后,自己 review 时检查是否遵守 AGENTS.md(命名、测试、提交信息),形成闭环。<br>
## 参考链接<br>
- [Skill 仓库](https://github.com/affaan-m/everything-claude-code)<br>
- [agents.md 规范(社区标准)](https://agents.md)<br>
- [Claude Code 官方文档](https://docs.anthropic.com/)<br>
- [Cursor Rules 文档](https://docs.cursor.com/)<br>
- [AGENTS.md 示例(Anthropic 官方)](https://github.com/anthropics/skills)<br>
- [项目规范最佳实践(Google)](https://google.github.io/eng-practices/)