入口文件不是垃圾桶

05 入口文件不是垃圾桶

标题备选

• 你的 AGENTS.md 不是垃圾桶
• AI 工作区入口文件怎么写？越克制越专业
• 别把所有上下文都塞进入口文件

开场钩子

很多人第一次理解入口文件时，会犯一个错误：既然 AI 进入工作区会先读它，那我就把所有重要内容都塞进去。

这听起来很合理，但实际上很危险。

正文口播

入口文件当然重要。

它是 AI 进入工作区时最先看到的上下文，决定了 AI 对项目的第一印象。

但正因为它重要，它才不能成为垃圾桶。

一个塞满所有背景、规则、历史、任务、示例和废弃信息的入口文件，很快会失去导航能力。

入口文件最该承担三个职责。

第一，说明工作区定位。

AI 需要知道这里是写作项目、软件项目、研究项目，还是通用模板。

它需要知道本工作区的目标、边界和默认语言。

比如：本项目用于撰写一本 ACW 技术书，正式正文写入 projects，过程产物写入 artifacts。

第二，提供目录路由。

AI 不应该猜每个目录的用途。

入口文件应该清楚说明：projects 存最终项目，background 存稳定背景，conventions 存协作规则，artifacts 存过程产物，tmp 存临时文件。

更进一步，它还可以告诉 AI：做写作任务前读取哪些规则，做审校任务前读取哪些标准，初始化已有项目时走哪条流程。

第三，写下最高优先级约束。

有些规则不应该藏在很深的文档里。

比如：不要编造真实事实；不要覆盖用户未要求修改的文件；最终产物不要写到过程目录；默认中文沟通；遇到隐私和高风险领域要标注待确认。

这类规则应该放在入口文件，或者让入口文件明确指向对应规范。

那入口文件不应该承担什么？

它不应该保存全部背景。背景应该放在 background。

它不应该保存每次任务记录。任务过程应该放在 artifacts。

它不应该保存最终成果。最终成果应该放在 projects。

它也不应该不断堆叠临时提醒。

临时提醒如果只对当前任务有效，应该进入任务 artifact。如果长期有效，应该整理成规范，再进入 conventions。

一个好的入口文件，像机场大厅的指示牌。

它告诉你登机口在哪里、安检在哪里、行李在哪里，但不会把每一架飞机的维修手册都贴在墙上。

这引出 ACW 的另一个核心机制：按需加载。

AI 的上下文窗口有限。即使模型越来越强，也不意味着我们应该把整个项目一次性塞进去。

更好的方式，是让 AI 先读取入口文件，再根据任务目标选择需要的子目录和文件。

根入口文件只保存全局地图。background 下面可以有自己的索引。conventions 下面也可以有自己的索引。某个具体项目下也可以有自己的 AGENTS.md，说明项目结构、当前状态和特殊约束。

AI 不是漫无目的地读文件，而是一层一层定位。

这种设计有两个好处。

第一，节省上下文。

写一章书时，AI 不需要读取所有历史任务。改一个组件时，它不需要读取运营计划。

第二，降低污染。

过期设定、废弃方案、临时假设、错误示例，如果混入当前上下文，AI 可能会把它们当成有效信息继续使用。

通过分层和索引，你能让 AI 更容易识别哪些是稳定事实，哪些只是过程记录，哪些已经废弃。

结尾引导

写入口文件时，可以记住一个原则：

只放跨任务、跨会话、跨目录都重要的信息。

入口文件不是越长越专业。越能帮助 AI 快速定位，才越专业。

下一集，我们讲 ACW 中后期最重要的目录：conventions。