项目指令文件该写什么:四份短例
文章从 28 个 Next.js 和 NestJS 应用提炼四份项目指令示例,重点记录命令、端口、跨应用关系和隐蔽约定。建议按根目录与应用目录分层维护,省去代码中容易查到的目录树和依赖清单。
AI 深度解读
给 AI 编程助手写项目说明,最有用的内容往往只有几十行:在哪个目录执行命令、项目有哪些特殊约定、哪些改动会悄悄破坏另一种运行模式。作者从自己交付的 28 个 Next.js 和 NestJS 应用中提炼出四份示例,主张每份 CLAUDE.md 控制在 200 行以内,删掉模型打开仓库就能看到的信息。
这篇值得看的地方,是它把「遵循项目规范」拆成了能检查的具体要求。但这些案例来自同一团队销售的模板项目,证明了约定确实存在,还不能证明采用这些文件后,AI 的出错率下降了多少。
该写进文件的,是命令和容易踩的坑
作者用只读 Node 脚本 facts.mjs 扫描 12 个仓库,覆盖 28 个应用,其中 19 个使用 Next.js 16,9 个使用 NestJS 10 到 12。2026 年 11 月 14 日的扫描结果显示:
- 28 个应用全部使用 Yarn 4,依赖、resolutions 和 overrides 全部精确锁定版本,没有版本范围。
- 每个应用都有
.env.example,合计 376 个环境变量名。 - 19 个前端全部使用 next-intl、react-hook-form 和 zod,其中 16 个把接口放在
src/lib/api,通过src/services中的 TanStack Query hooks 读取。 - 28 个应用都没有 test 脚本;19 个前端中,17 个使用
typecheck,1 个使用type-check,还有 1 个没有类型检查脚本。
最后一条最能解释作者的思路。写「修改后运行测试」很像正确建议,但放进这些项目,只会让助手尝试不存在的命令。
项目说明应该告诉助手实际能执行什么,而不是项目理应具备什么。
Northstack 的根文件因此明确:命令必须在各应用目录执行;前端运行 yarn typecheck && yarn lint;API 没有 typecheck 脚本,使用 yarn build && yarn lint。启动可以执行 docker compose up --build,也可以先运行 cd back-end && yarn seed && yarn dev,等待 /api/health 就绪,再启动前端。
端口也值得写:website 是 3030,dashboard 是 3031,API 是 8000,均不能套用 Next.js 默认的 3000。
作者的四份示例只有 34 到 43 行,根文件为 41 行、2,075 字符。它们保留了少量应用位置说明,因为这里的目录关系直接决定命令在哪执行;没有展开完整文件树和依赖清单。
分层文件能减少上下文,导入文件不能
按原文描述,Claude 启动时会加载当前目录及上级目录中的说明文件,它们会合并,不会简单覆盖。靠近当前目录的文件最后读取,但冲突规则仍可能产生歧义,因此同一条规则应只维护一处。
作者采用根目录加应用目录的结构:根文件负责共享约定,dashboard 文件负责前端细节,back-end 文件负责 API。子目录的 CLAUDE.md 只在助手读取、写入或编辑该目录文件时加载,避免 API 任务一直携带前端规则。
个人偏好可以放在 ~/.claude/CLAUDE.md;项目共享说明可以放在 ./CLAUDE.md 或 ./.claude/CLAUDE.md;本地项目笔记则放在不提交 Git 的 ./CLAUDE.local.md。
更细的规则可以放进 .claude/rules,用 paths 限定触发范围。这段原文代码解决的是翻译文件容易漏键、漏注册的问题:
---
paths:
- "**/messages/**/*.json"
---
- Every key exists in both `en.json` and `ar.json` of the same namespace.
- A new namespace file is listed in `website/src/i18n/request.ts` (website)
or `dashboard/src/config/dashboardNamespaces.ts` (dashboard), or it never loads.
要看的是 paths 和后面的注册要求:文件存在,不代表应用会加载它。这类跨文件约束,比「注意国际化」更能指导修改。
@AGENTS.md 则解决多工具共享说明的问题。原文称导入最多支持四层,但被导入内容会一起进入上下文,不能靠拆文件节省 token。可以通过 /context all 中的 Memory files 检查实际加载结果。
兼容性也有版本前提:原文称 Claude Code 从 v2.1.277 起,在当前目录及上级没有 CLAUDE.md、CLAUDE.local.md 时会读取 AGENTS.md;两者并存时默认只读取 CLAUDE.md,除非在 /config 中把 Project instructions 设置为 claude-md-and-agents-md。共享方案是让 CLAUDE.md 导入 AGENTS.md,再补充 Claude 专属内容。Codex 默认累计读取上限则为 32 KiB。
这些属于原文给出的版本行为,不能脱离版本当成永久规则。
最有价值的规则,是指出改动会连带破坏哪里
Northstack 的前端存在两条运行路径:配置 NEXT_PUBLIC_API_BASE_URL 时调用 API,留空时使用 src/lib/mock/ 中的样例数据。
所以新增接口不能只写请求函数。还要增加 mock handler,否则真实 API 能用,样例模式却返回 404。字面路由 /projects/archived 也必须排在 /projects/:projectId 前面,避免被参数路由截走。
数据层约定同样具体:接口放在 src/lib/api/<domain>/,页面通过 src/services/<domain>/ 中的 TanStack Query hooks 调用;响应遵循 { success, data, message }。作者还指定 src/features/dashboard/billing/ 作为可复制范例,减少助手自己猜目录结构的空间。
国际化也有类似的隐性依赖。消息位于 messages/<namespace>/<locale>.json,每个 namespace 都有 en.json 和 ar.json。dashboard 新增 namespace 后,必须更新 src/config/dashboardNamespaces.ts,否则页面会显示原始 key。

阿拉伯语支持解释了为什么团队强调 ms-*、pe-*、start-*、text-start 等逻辑方向类。扫描的 6,969 个组件文件中,有 3,467 处逻辑方向类和 189 处物理方向类;后者不少是 left-1/2 这样的居中定位,不能把所有 left-* 都机械判错。
API 的说明则围绕另一组依赖:全部路由带 /api 前缀,DTO 使用 class-validator,全局 ValidationPipe 开启 whitelist 和 forbidNonWhitelisted。字段没有校验装饰器,可能直接得到 400。
数据库默认 SQLite,也支持通过 DB_TYPE=mysql 切到 MySQL,因此查询要兼容两者。9 个 API 都只在开发环境同步 schema,其中 8 个没有 migrations 目录。Northstack 的生产变更流程是备份后运行 yarn schema:prod;接口返回结构变更后,还需在 API 已启动并完成 seed 的条件下执行 yarn export:mock,更新两个前端的样例数据。
这些才是助手不一定会主动追查、却直接影响交付结果的信息。
我的判断
我认同作者把说明文件当成「重复纠错记录」的做法。比起写一篇架构导览,记录准确命令、现有范例和跨文件约束,更容易判断助手有没有照做。/init 可以起草文件,但作者强调后续工作主要是删减,这个取舍合理。
不过,28 个应用来自同一团队的 12 个商品仓库,技术选型和工程习惯高度接近。扫描结果能支撑「这些规则符合他们的代码」,不能支撑「所有 Next.js、NestJS 团队都应该采用同样规则」。精确锁版本、没有 migrations、没有测试套件,都需要结合自己的项目判断。
原文也没有给出使用前后的任务成功率、返工次数或上下文消耗对照。「短而具体更好」有清晰理由,目前仍属于工程经验,200 行不是经过实验验证的分界线。
CLAUDE.md 是行为指导,不能替代权限控制、校验器和 CI。
例如作者要求只有明确被要求时才能运行 yarn reset、yarn drop,也承认硬限制应交给 deny rule。但提供的原文没有展开对应配置,不能把这一条文字约定当成已落实的保护措施。
原文还称,从 Next.js 16.3 起,next dev 检测到编程助手后会向 AGENTS.md 写入指向 node_modules/next/dist/docs/ 的托管内容。作者全部 19 个前端都配置 agentRules: false,这是他们选择自行维护说明的结果,不代表其他项目也该关闭。
此外,输入在第四份 AGENTS.md 示例中途截断,开头提到的免费 nextjs-claude-md skill 没有完整实现可供检查。这里不能替它确认检查器的覆盖范围。
能拿来做什么
- 先核对各应用的
package.json和.env.example,写清命令执行目录、端口、启动顺序和已有检查。没有 test 脚本,就明确记录当前验证手段。 - 给前端助手留下一个真实范例目录,并写出页面、请求函数、TanStack Query hooks 和 mock handler 的衔接关系,让新增功能沿着现有路径完成。
- 把多语言键同步、namespace 注册等要求放进按路径加载的规则,完成后用
/context all核对加载结果,避免文件写了却没进入任务上下文。 - 每次纠正助手时,判断问题是否会再次出现。值得长期记录的约定写进说明;可以自动检测的错误逐步交给 lint、类型检查或 CI。