ACORG docs

主题

项目规则文件指南 ​

项目规则文件用于把仓库背景、命令、编码约定和验收标准交给 AI 客户端。它不能替代测试和代码审查,但能显著减少重复解释。

常见规则来源 ​

工具推荐文件 / 位置适合内容
CodexAGENTS.md仓库约定、构建命令、测试要求、目录边界
Claude CodeCLAUDE.md项目背景、Claude 工作方式、常用命令
Cursor.cursor/rules按文件、目录或任务范围生效的编辑器规则
Qoder项目记忆 / Rules业务知识、团队流程、长任务上下文
通用文档README.md / docs/人类也需要阅读的长期项目说明

推荐写法 ​

规则文件应短、明确、可验证。优先写这些内容:

  • 项目是什么,不要做什么。
  • 包管理器、启动命令、构建命令、测试命令。
  • 代码风格、目录职责和禁止跨越的边界。
  • 修改后必须运行的验证。
  • 安全、权限、数据、密钥和外部服务限制。
  • 常见任务流程,例如新增页面、组件、接口、迁移脚本。

示例 ​

md
# 项目约定

## 项目背景

这是一个 VitePress 文档站,内容位于 docs/。

## 命令

- 安装依赖: npm install
- 本地预览: npm run docs:dev
- 构建验证: npm run docs:build

## 文档规范

- 新页面必须加入 .vitepress/config.mts 的 sidebar。
- 内部链接使用相对路径或站点绝对路径。
- 强时效内容要写明最后核对日期和官方来源。

## 验证

修改文档后运行 npm run docs:build。

同步策略 ​

多客户端并用时,不要让每个工具各写一套互相冲突的规则。建议:

  1. 把长期规则放在 AGENTS.md 或团队统一文档中。
  2. 给 Claude Code、Cursor、Qoder 只补它们特有的入口和格式。
  3. 规则变更后同时更新相关客户端文件。
  4. 每次新增工具前先检查已有规则,避免重复和冲突。

不建议写入 ​

  • API Key、Token、Cookie、私有证书。
  • 大段业务数据或完整日志。
  • 和代码不一致的旧命令。
  • “永远”“必须”但没有验收标准的宽泛指令。
  • 可以由格式化器、lint、测试自动约束的长篇口头规范。

和 Skill / MCP 的关系 ​

  • 规则文件:约束当前仓库的长期协作方式。
  • Skill:封装可复用任务流程,适合跨项目复用。
  • MCP:连接外部工具和数据,适合读取 issue、设计稿、文档或运行 IDE 能力。

相关文档 ​