AI 助手进入陌生仓库时，最容易浪费时间在猜测启动方式、目录职责和团队约定。把稳定规则写进仓库，比每次对话重复说明更可靠。
1. README 负责项目全貌
包含项目用途、技术栈、最低环境版本、安装方式、启动命令和常见故障。把真正能运行的命令放在显眼位置。
2. 目录说明负责所有权
说明核心目录分别存放页面、服务、数据访问、测试和生成文件。对自动生成目录标记“不要手工编辑”。
3. 规则文件负责执行约束
记录格式化命令、测试范围、命名风格、依赖策略以及提交前必须完成的检查。规则应短而明确，避免充斥背景故事。
4. 让文档与代码一起维护
命令、版本或目录变化时同步更新说明，并在代码评审中检查文档是否过期。失真的文档比没有文档更危险。
常见误区
- 文档只写安装不写验证
- 目录职责与实际代码不一致
- 把临时决定写成永久规则
- 规则过多且互相冲突
执行检查清单
- 新成员可按文档启动项目
- 核心目录职责明确
- 检查命令可直接复制执行
- 生成文件与敏感文件已标注
总结
仓库上下文的目标不是写百科全书，而是消除高频猜测。每条说明都应能帮助执行者做出更准确的下一步。