AI Agent / 系统课时
建立项目协作说明
建立项目协作说明
稳定的 Claude Code 协作依赖可复用的项目规则,而不是每次重新解释。本课创建简洁的 CLAUDE.md,记录架构边界、常用命令、编码约定和权限基线,并验证它能被项目会话正确读取。
学习目标
- 编写只包含高价值规则的
CLAUDE.md - 记录可复制的构建、测试和检查命令
- 建立默认只读、按需写入的权限基线
决定哪些内容值得长期保存
CLAUDE.md 适合保存长期稳定、会影响多数任务的规则,例如模块职责、禁止依赖方向、统一测试命令和安全限制。某个 Issue 的临时背景、一次性文件路径和个人偏好不应写入项目级说明。
文件越长并不越好。重复 README、粘贴完整 API 文档或罗列所有目录,会挤占上下文并让关键规则失焦。每条规则都应能回答“违反它会造成什么问题”。
编写最小可用文件
下面是一个可直接改造的项目级示例。命令必须替换为仓库真实可运行的内容。
# Project Instructions
## Architecture
- `src/api` 只负责协议适配,不写业务规则。
- `src/domain` 不得依赖 `src/web`。
- 公共接口变更必须同时更新契约测试和文档。
## Commands
- 安装依赖:`npm ci`
- 单元测试:`npm test`
- 静态检查:`npm run lint`
- 构建:`npm run build`
## Coding Rules
- 保持现有 TypeScript 严格模式。
- 不新增依赖,除非任务明确批准。
- 修复缺陷时先补失败测试,再修改实现。
## Safety
- 不读取或输出 `.env`、私钥和生产凭据。
- 不执行部署、数据库迁移或远程删除命令。
- 修改超过五个文件前,先给出计划并等待确认。生效行为
新项目会话读取这些说明后,应按指定架构、命令和安全限制制定计划与执行任务。这是配置文档,不保证所有规则都能替代系统级权限控制;高风险操作仍应由工具权限和隔离环境限制。
校验命令是否真实
不要把“可能可用”的命令写进说明。应在干净工作区实际运行安装、测试、检查和构建,并记录必要前置条件。命令若依赖服务、环境变量或容器,要在同一节说明最小启动方法。
可使用 Claude 做只读核对,但最终以命令退出码为准:
# 在干净环境中依次验证项目记录的标准命令
npm ci
npm test
npm run lint
npm run build预期结果
<ALL_COMMANDS_EXIT_WITH_CODE_0>具体日志随项目变化。某个命令暂时失败时,应记录已知原因,而不是把失败命令写成“标准验证”。
设置权限基线
项目说明可以要求“先计划后编辑”,但它不是权限系统。默认会话应从只读分析开始,确认计划后才开放 Edit 或 Bash;CI 和 Agent SDK 中则使用工具白名单、沙箱和受限凭据。
团队还应明确哪些目录禁止自动修改,例如迁移历史、生成代码、生产部署配置和法律文本。需要修改这些区域时,应由人工显式批准。
验证上下文是否被读取
启动新会话后,让 Claude 简述项目边界、标准测试命令和禁止操作。若回答缺项,先检查文件位置、命名和内容是否清晰,再检查当前会话是否加载了项目设置。
不要通过在文件中加入隐藏指令测试加载情况。用可见、无副作用的问题验证即可,并把结果纳入项目初始化检查。