Scan the project structure; when necessary, the Claude main thread coordinates subagents to investigate modules in parallel, and finally generates a layered CLAUDE.md documentation index.
Usage
/ac-init [项目简述] [--modules]
Parameter description:
项目简述: Optional, a brief description of the project--modules: Optional; when this parameter is added, generate module-levelCLAUDE.mdfiles
Role division
| Role | Responsibility |
|---|---|
| Claude (main thread) | Obtain the timestamp, decide whether to enable subagents, aggregate scan results, and write the root-level and module-level CLAUDE.md |
| subagents | Read-only scanning of project structure, module responsibilities, key files, and dependencies; does not write files |
Execution constraints
Working directory:
- Use the current working directory as the project scan root directory
- If the user has added multiple workspaces via
/add-dir, first use Glob/Grep to determine the target workspace - If it cannot be determined, use
AskUserQuestionto ask the user to select the target workspace
Conditions for using subagents:
- Applicable: the project directory is large, there are many modules, and the structure or dependencies need to be investigated in parallel
- Preferred:
Exploreused for read-only scanning of project structure, entry files, module boundaries, and dependencies - Not applicable: small projects, simple directory structures, or scenarios that the main thread can complete with a few reads
Important:
- Only generate or update documentation files: root-level
CLAUDE.mdand module-levelCLAUDE.md - Do not modify any source code, configuration, or dependencies
- Subagents only perform scanning and analysis and do not write files
- For scan content already delegated to subagents, the main thread should not execute it repeatedly
- Skip generated artifacts and cache directories:
node_modules、dist、build、.git、__pycache__
Execution workflow
Step 1: Obtain timestamp + root-level scan
[模式:扫描]
- The main thread obtains the current timestamp
- The main thread first identifies the project type and minimal entry information:
- Project name (inferred from
package.json、pyproject.tomlor the directory name) - Tech stack (language, framework, build tools)
- Entry file
- Project name (inferred from
- If the project structure is simple: the main thread completes the scan directly
- If the project is large or has many directories: use the
Agenttool to startExploresubagents as needed, returning structured scan results:
{
"name": "项目名称",
"tech": { "language": "", "framework": "", "build": "" },
"entry": ["入口文件路径"],
"modules": [
{ "path": "模块路径", "name": "模块名", "role": "职责", "files": ["关键文件"] }
],
"commands": { "install": "", "dev": "", "test": "" }
}
Step 2: Generate root-level CLAUDE.md
[模式:写文档]
The main thread uses the Write tool to generate in the project root directory CLAUDE.md, with content including:
# {项目名称}
> 生成时间:{TIMESTAMP}
## 概述
{根据扫描结果写 1-2 句项目简述}
## 技术栈
- 语言:{language}
- 框架:{framework}
- 构建:{build}
## 项目结构
```mermaid
graph TD
ROOT[{项目名}]
ROOT --> M1[{模块1}]
ROOT --> M2[{模块2}]
Module index
| Module | Path | Responsibility |
|---|---|---|
| {name} | {path} |
{role} |
Entry file
{entry}- {description}
Quick commands
{commands.install}
{commands.dev}
{commands.test}
### 步骤 3:生成模块级 `CLAUDE.md`(仅当指定 `--modules`)
`[模式:模块分析]`
**跳过条件**:如果用户未指定 `--modules` 参数,跳过此步骤。
1. 主线程确定需要生成文档的模块列表
2. 若模块较多,使用 `Agent` 工具在同一轮并行启动多个 `Explore` subagents,按模块或模块组返回:
- 模块职责
- 关键文件
- 依赖:本模块依赖谁
- 被依赖:谁依赖本模块
3. 主线程汇总结果后,用 Write 工具在每个模块目录下创建 `CLAUDE.md`:
```markdown
# {模块名}
> [← 返回根目录](../CLAUDE.md) | 更新:{TIMESTAMP}
## 职责
{role}
## 关键文件
| 文件 | 职责 |
|------|------|
| `{file}` | {描述} |
## 依赖关系
- 依赖:{分析 import / 引用关系}
- 被依赖:{分析其他模块的 import / 引用关系}
Step 4: Output summary
[模式:总结]
## 初始化完成
### 生成文档
- ✅ `./CLAUDE.md`
- ✅ 模块级:{N} 个(仅当使用 `--modules` 参数时显示)
### 识别模块
1. `{path}` - {role}
### 推荐下一步
- [ ] 检查文档准确性
- [ ] 补充业务逻辑
- [ ] 如需模块级文档,使用 `/ac-init --modules` 重新生成
Rules
- Main thread writes files – all
CLAUDE.mdare generated by the main thread of the current session - Subagents only scan read-only – enabled only as needed, not enabled by default, and do not write files
- Only write documentation – do not modify source code
- Skip generated artifacts –
node_modules、dist、build、__pycache__、.git - Module identification – prioritize identifying items containing
__init__.py(Python) orindex.*directory of (JS/TS)
Mermaid specification
- Root level:
graph TD(top-down) - Module level:
graph LR(left-to-right) - Node IDs use camelCase