AI Agent / 系统课时

建立项目协作说明

建立项目协作说明

稳定的 Claude Code 协作依赖可复用的项目规则,而不是每次重新解释。本课创建简洁的 CLAUDE.md,记录架构边界、常用命令、编码约定和权限基线,并验证它能被项目会话正确读取。

学习目标

  • 编写只包含高价值规则的 CLAUDE.md
  • 记录可复制的构建、测试和检查命令
  • 建立默认只读、按需写入的权限基线

决定哪些内容值得长期保存

CLAUDE.md 适合保存长期稳定、会影响多数任务的规则,例如模块职责、禁止依赖方向、统一测试命令和安全限制。某个 Issue 的临时背景、一次性文件路径和个人偏好不应写入项目级说明。

文件越长并不越好。重复 README、粘贴完整 API 文档或罗列所有目录,会挤占上下文并让关键规则失焦。每条规则都应能回答“违反它会造成什么问题”。

编写最小可用文件

下面是一个可直接改造的项目级示例。命令必须替换为仓库真实可运行的内容。

markdown
# 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`、私钥和生产凭据。
- 不执行部署、数据库迁移或远程删除命令。
- 修改超过五个文件前,先给出计划并等待确认。

生效行为

text
新项目会话读取这些说明后,应按指定架构、命令和安全限制制定计划与执行任务。

这是配置文档,不保证所有规则都能替代系统级权限控制;高风险操作仍应由工具权限和隔离环境限制。

校验命令是否真实

不要把“可能可用”的命令写进说明。应在干净工作区实际运行安装、测试、检查和构建,并记录必要前置条件。命令若依赖服务、环境变量或容器,要在同一节说明最小启动方法。

可使用 Claude 做只读核对,但最终以命令退出码为准:

bash
# 在干净环境中依次验证项目记录的标准命令
npm ci
npm test
npm run lint
npm run build

预期结果

text
<ALL_COMMANDS_EXIT_WITH_CODE_0>

具体日志随项目变化。某个命令暂时失败时,应记录已知原因,而不是把失败命令写成“标准验证”。

设置权限基线

项目说明可以要求“先计划后编辑”,但它不是权限系统。默认会话应从只读分析开始,确认计划后才开放 Edit 或 Bash;CI 和 Agent SDK 中则使用工具白名单、沙箱和受限凭据。

团队还应明确哪些目录禁止自动修改,例如迁移历史、生成代码、生产部署配置和法律文本。需要修改这些区域时,应由人工显式批准。

验证上下文是否被读取

启动新会话后,让 Claude 简述项目边界、标准测试命令和禁止操作。若回答缺项,先检查文件位置、命名和内容是否清晰,再检查当前会话是否加载了项目设置。

不要通过在文件中加入隐藏指令测试加载情况。用可见、无副作用的问题验证即可,并把结果纳入项目初始化检查。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

建立项目协作说明

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通