AI Coding 时代，你们项目里会维护 AGENTS.md 或 CLAUDE.md 吗？

zyh941109 2026-06-09 12:45 1

最近在做 AI 辅助开发相关的实践，发现如果给工具补充清晰的项目上下文和规范（类似“项目记忆”），代码生成的质量和一致性会明显提升。

想调研一下大家现在的做法：

大家在项目里会专门维护类似下面这种 AI 协作规范文件吗？

AGENTS.md（Codex、Cursor 等工具可读取）

CLAUDE.md（Claude Code 使用）

如果有维护的话，一般会写哪些内容？

比如但不限于：

项目结构说明

技术栈约定

代码规范（lint / format / 命名等）

Git 提交规范

测试要求

ADR / 架构决策记录

开发流程 / CI 流程

Todo / 任务流转规则

其他“给 AI 看的说明”

目前我们团队是开始尝试把这些内容逐步沉淀下来，感觉对 AI 理解项目上下文挺有帮助的。

想看看大家的实践情况：

现在是“各写各的”，还是已经有比较统一的最佳实践了？有什么踩坑经验也欢迎分享

最新回复 (19)

Hifumi Mizuhara 06-09 12:46

1楼

当然是让Claude自己更新自己的Claude.md啦
frank2026 06-09 12:47

2楼

会，我遇到重复出现的问题，我就会问cc如何避免，他会给建议，写到哪里
jcc 06-09 12:48

3楼

两个同时用就很麻烦

我现在是CLAUDE.md里面，写一句话，“开始工作前请先读AGENTS.md，遵循AGENTS.md的指引”

然后只维护AGENTS.md

总觉得不太优雅
iawnix 06-09 12:49

4楼

我甚至写了一个定时任务，让codex自己每天归纳维护，后面发现效果不佳就取消了。我是单独创建了一个workspace让codex把所有的项目都放在这个工作区。但是随着项目越来越多，这个AGENT.md会膨胀的越来越大，后面就让codex进行了拆分，但是效果还是不佳。

比如一个APP，每次更新让迭代一个小版本。但codex进行更新的时候，还是不会遵循这个约定，有些时候不会分配小的版本号。
Carson 06-09 12:50

5楼

我都是先做，做完一个之后如果觉得这个部分很重要，就让ai自己写进自己的文档里。同时还会专门维护一个docs文件夹，里面分类放置各种说明，然后agents.md里开头第一句就是先阅读docs里的针对性内容
zyh941109 楼主 06-09 12:52

6楼

我使用的方案跟你一样，读取 CLAUDE.md → 按说明读取 AGENTS.md 。

Claude Code 项目说明

请先阅读并遵循仓库根目录下的 AGENTS.md。

AGENTS.md 是本项目唯一主 AI 协作规范。

本文件只用于让 Claude Code 找到规则入口，不重复维护完整规则。

项目事实、编码约定、API 边界和任务状态应维护在 docs/ 与 tasks/ 下，而不是写入本文件。
zyh941109 楼主 06-09 12:54

7楼
me too！

AGENTS.md开始非琐碎任务前，按需阅读：
1. docs/architecture.md — 项目结构与技术栈
2. docs/conventions.md — 编码规范与文件组织
3. docs/api.md — API / 外部服务使用约束
4. docs/decisions.md — 已确认的长期架构决策
5. tasks/lessons.md — 历史经验
6. tasks/todo.md — 当前任务状态
钟阮 06-09 12:57

8楼

我只维护AGENTS.md，然后CLAUDE是硬链接过去的，

然后AGENTS.md是让Codex在Goal一行行对着 https://agents.md/ 去写的
千早爱音 06-09 13:05

9楼

Claude Code 文档中已经给了解决方案，在 CLAUDE.md 中加一句 @AGENTS.md 即可
phaseddd 06-09 13:13

10楼

基本不维护了，单文件不够用，需要记的多了就会不受控制往最前面无脑加，所以现在基本是按自己的规划维护doc\docs文件夹，然后需要记下的准则交给MEMORY结合使用，AGENTS.md或者CLAUDE.md里面最多写一个对doc\docs文件夹的引用说明
憨憨和Nike 06-09 14:19

11楼

哈哈，所以我现在都是用 openclaw，就看中他的记忆系统，本地装一个 qmd。写代码的话让他去调用 coding agent ，很不错
老文 06-10 09:09

12楼

主要精力就是维护这些规则文件是skills
阿萨Aza 06-10 09:16

13楼

这根本就不算解决方案，正确的解决方案是: 使用硬链接
乐坏小陈 06-10 11:44

14楼

我之前都是看harness相关的实践方案才知道，原来AGENTS.md/CLAUDE.md也可以约束开发中的一些流程、开发边界、规则等等。我之前甚至用AGENTS.md + /docs目录自己搞了一套小型的 SDD 流程开发的规则，这样就无需安装额外的 superpowers 之类的。仅通过AGENTS.md就可以在每轮开发中让Agent自行维护文档说明
苗大 06-10 11:46

15楼

用软链呗，只用维护AGENTS.md

Windows的话记得系统里开下开发者模式才能用软链
feiniaozty 06-10 11:49

16楼

跟我差不多，确实这种方法更好，因为claude.md维护太久之后噪声太多了。在docs里面就可以自己做拆分
太阳之子 06-10 11:51

17楼

肯定要维护，我只维护claude.md，agents.md懒得维护，反正我也只用claude code，不用其他的。

如果项目庞大的话最好还是分多个文档维护。
BHznJNs 06-10 11:51

18楼
我的理解是：AGENTS.md 由于是每个任务的上下文中都必定带的，所以其中的内容应该是模型在这个项目中工作必须的上下文，对于非必须的内容有两个处理方式：
1. 拆分成单独 markdown 文件，在 AGENTS.md 写明特定情况下读取
2. 对于项目特定的信息放在 memory 中，对于通用信息放在 skill 中
1076718373 06-10 11:57

19楼
1. 只维护一份AGENTS.md，然后CLAUDE.md软连接到AGENTS.md。
2. AGENTS.md只有项目整体框架、架构和路由到子规范的说明，子规范在docs/*.md。
3. 整体的规范都是让ai来作的，然后开发中遇到问题了在让ai加规范。