/project-init

AGENTS.md 生成模板与指南

本文件定义各项目类型 AGENTS.md 应包含的段落和生成方式。 Claude 应基于全局协议 ~/.claude/CLAUDE.md 和项目分析结果生成真实内容，不是复制模板。

生成后，CLAUDE.md 仅写入 @include ./AGENTS.md，不重复内容。两个文件共享同一份项目协议。

目录

• simple
• development
• frontend
• comprehensive-development
• data-analysis
• skill-project

simple

适用于：法律文档项目、内容写作项目。

仅引入全局协议：

@include ~/.claude/CLAUDE.md

development

适用于：通用开发项目。

应从项目分析中提取的真实信息：

• 项目名称和简介（README / package.json description）
• 技术栈（package.json dependencies / pyproject.toml / Cargo.toml）
• 开发命令（package.json scripts / Makefile）
• 目录结构（扫描 src/ lib/ app/ 等关键目录）

结构：

# {{PROJECT_NAME}}

@include ~/.claude/CLAUDE.md

## 项目简介
[从 README 或代码分析得出]

## 技术栈
[从依赖文件提取]

## 开发命令
[从 scripts 提取实际命令]

## 文件清单
[对齐全局协议的文档体系表格]

## 关键设计决策
[从代码和文档分析得出]

## 项目特定规则
[基于项目特点生成的协作规则]

生成范例（脱敏）：

# {{PROJECT_NAME}} 项目协作指南

## 项目简介

{{PROJECT_NAME}} 是一个 {{一句话描述项目用途}}。
技术栈：{{从依赖文件提取，如：框架 + 语言 + 构建工具 + 关键库}}

## 基本约定

- 全程使用中文回复与写作
- 遵循 `docs/ROADMAP.md` 路线图驱动开发
- 重要决策记录到 `docs/DECISIONS.md`
- 用户可见变更写入 `CHANGELOG.md`

## 文件清单

| 文档 | 位置 | 职责 |
|------|------|------|
| README.md | 根目录 | 项目介绍、快速开始 |
| CHANGELOG.md | 根目录 | 版本变更记录 |
| ARCHITECTURE.md | docs/ | 系统架构、数据流、模块说明 |
| ROADMAP.md | docs/ | 路线图、阶段任务、进度日志 |
| DECISIONS.md | docs/ | 技术决策记录 + 工作日志 |
| TASKS.md | docs/ | 当前任务入口、完整任务卡与验收证据 |

## 开发命令

\```bash
npm install          # 安装依赖
npm run dev          # 启动开发模式
npm run build        # 构建生产版本
\```

## 关键设计决策

- {{从代码/文档中提取的已确定技术选型}}
- {{关键架构决策，每条一行}}

frontend

适用于：前端 UI 项目。

在 development 基础上增加：

额外提取：

• 样式方案（tailwind.config / css modules）
• 组件库（dependencies 中的 UI 库）
• 设计系统位置（DESIGN.md）

额外结构：

## 设计规范
- 设计系统：DESIGN.md
- 组件库：[从依赖提取]
- 响应式策略：[分析得出]

## 目录结构约定
[从实际 src/ 结构提取]

comprehensive-development

适用于：结构复杂的大型开发项目（多层级架构、多 Agent 协作、有完整测试体系）。

在 development 基础上，以下段落按需组装。生成时从项目分析中提取真实内容填入对应结构，不是复制空模板。

可选段落清单

段落结构模板

开发前置阅读

## 开发前置阅读

每次开始开发前（无论新功能还是修改），MUST 按以下优先级阅读项目文档：

1. `AGENTS.md`（本文件）— 协作规则、架构边界、禁止事项
2. `docs/ARCHITECTURE.md` — 系统分层、数据流
3. `DESIGN.md` — 前端开发遵循的设计规范（如有前端）
4. `docs/ROADMAP.md` — 当前阶段任务与完成状态
5. `docs/DECISIONS.md` — 最近决策和工作日志
6. 项目自选任务源文件（如适用）— 当前状态、完整任务卡与验收要求

架构分层与边界

## 架构分层

{{PROJECT_NAME}} 的代码分为 {{N}} 个明确层级，AI 在判断改动范围时必须按此归类：

\```
{{层 1 名称}}（{{路径}}）
  ├── {{关键文件}}  ← {{职责}}
  └── ...
      │
      ▼
{{层 2 名称}}（{{路径}}）
  ├── {{关键文件}}  ← {{职责}}
  └── ...
\```

### 层级职责

| 层级 | 职责 | 可修改范围 |
|------|------|-----------|
| **{{层名}}** | {{职责}} | {{什么情况下可以改}} |

### 边界规则

- {{跨层调用的唯一路径，如"前端不得直接调用底层 API，必须通过中间层"}}
- {{新增命令/接口时必须同步更新的文件}}

禁止事项

## 禁止事项

| 禁止 | 后果 | 正确做法 |
|------|------|----------|
| {{具体操作}} | {{为什么不能做}} | {{应该怎么做}} |

测试层级

## 测试层级

| 层级 | 测什么 | 命令 | 覆盖范围 |
|------|--------|------|----------|
| **L1：{{名称}}** | {{范围}} | `{{命令}}` | {{覆盖模块}} |
| **L2：{{名称}}** | {{范围}} | `{{命令}}` | {{覆盖模块}} |

### 运行时机

| 场景 | L1 | L2 |
|------|----|----|
| 修改了 {{模块}} | MUST | — |
| 修改了 {{模块}} | — | MUST |
| 合并 PR 前 | MUST | MUST |

待办事项分组与并行调度

## 待办事项分组与并行调度

三维度分组评估：

| 维度 | 说明 | 判定规则 |
|------|------|----------|
| 文件重叠度 | 涉及相同文件/组件的待办事项 | 重叠 → 必须同分支处理 |
| 依赖链 | B 需要 A 的产出才能工作 | 有依赖 → 同分支顺序完成 |
| 并行安全度 | 不同组的文件集是否完全不重叠 | 无重叠 → 可并行 worktree |

实施范围说明

## 实施范围说明

### 实施前：范围说明

- **目标**：用户想改什么
- **涉及文件**：哪些文件最可能会动
- **保护范围**：哪些模块这次不应改动

### 实施后：影响回报

- 实际改了哪些文件
- 哪些核心模块保持不变
- 是否引入了新的数据字段、状态或接口

data-analysis

适用于：数据分析 / Notebook 项目。

应提取的真实信息：

• Python 环境（requirements.txt / conda env）
• 主要分析库（pandas, matplotlib 等）
• 数据位置
• Notebook 命名/组织方式

结构：

# {{PROJECT_NAME}}

@include ~/.claude/CLAUDE.md

## 分析环境
[从依赖文件提取]

## 数据源
[从目录结构和文件分析]

## 项目特定规则
[Notebook 约定、图表样式等]

## 常用命令
[从 Makefile / scripts 提取]

## 目录结构约定
[从实际结构提取]

skill-project

适用于：Claude Code Skill 开发项目。

在 legal-skills monorepo 内：

@include ./AGENTS.md

独立 skill 项目：

@include ~/.claude/CLAUDE.md

## Skill 开发规范
- 本项目是一个 Claude Code Skill
- 目录结构遵循 skill-standards 规范
- SKILL.md 不超过 500 行，代码块超过 20 行放入 scripts/
- references/、scripts/、assets/ 必须扁平（无嵌套子目录）
- description 必须包含触发场景和负向条件