agent-init-deep

用途

agent-init-deep 用于初始化或迁移到嵌套式 CLAUDE.md 结构，实现渐进式披露（Progressive Disclosure）。它把项目指导信息按加载时机分层，避免根 CLAUDE.md 过于臃肿。

上下文模型

技能将上下文分为三层：

静态（根 CLAUDE.md）：每次对话都加载，内容最少、价值最高。
半动态（docs/agents/）：从根文件链接，跟随链接时才加载。
完全动态（skills）：由元数据匹配触发，仅在调用时加载。

根 CLAUDE.md 必须控制在 40-50 行以内，其余内容放入 docs/agents/ 或 skills。

目标结构

CLAUDE.md                        # 根：身份、技术栈、关键规则、工作流、链接
docs/agents/
├── tooling.md                   # 例如包管理器、lint、格式化、hooks
├── commands.md                  # 例如脚本执行、构建过滤、传参
├── guardrails.md                # 例如数据隔离、密钥、库文档
├── definition-of-done.md       # 例如覆盖率、lint、类型检查、格式要求
└── [topic].md                   # 按需添加的其他主题文件

工作流

第 1 步：检测状态

检查：CLAUDE.md 是否存在、docs/agents/ 是否存在、CLAUDE.md 有多少行。

没有 CLAUDE.md → 走全新创建路径。
已有 CLAUDE.md → 走迁移路径。

第 2a 步：全新创建路径

向用户询问：项目名称与一句话描述、技术栈（前端、后端、数据库等）、包管理器（pnpm、npm、yarn、bun）、关键护栏（多租户、密钥等）、完成定义（测试覆盖率、lint、类型、格式）。

然后生成根 CLAUDE.md，包含：项目身份（1-2 行）、技术栈列表、3-5 条关键规则（只写智能体在无人提醒时经常做错的事）、四阶段工作流（Plan → Execute → Validate → Commit）、带路由信号的 docs/agents/ 文件链接。

再根据回答生成 docs/agents/ 文件，常见文件包括：tooling.md（包管理器规则、lint 配置、hooks）、commands.md（如何运行脚本、按包过滤、传参）、guardrails.md（数据隔离、密钥、库文档）、definition-of-done.md（具体阈值和命令）。文件名和主题可按项目实际需要调整。

第 2b 步：迁移路径

读取现有 CLAUDE.md。
对每个章节分类：根级（身份、技术栈、3-5 条关键规则、工作流）、docs/agents/ 级（详细的工具、命令、护栏、完成定义）、技能级（复杂工作流、流程、领域专业知识）。
向用户展示拆分方案，列出根 CLAUDE.md 保留内容以及各 docs/agents/ 文件将提取的章节。
请用户确认或调整。
创建 docs/agents/ 文件。
重写根 CLAUDE.md。

第 3 步：设置后处理

创建结构后：列出所有创建的文件、展示根 CLAUDE.md、建议进一步改进，例如在应用子目录中添加 CLAUDE.md 以存放应用专属规则、运行 /agent-add-rule 把新规则加到正确位置、运行 /skills 查看可用技能。

根 CLAUDE.md 模板

# Project Context

[One-line project description]

## Tech Stack

- [list technologies]

## Key Rules

- [3-5 rules the agent consistently gets wrong without being told]

## Workflow

Every task follows four stages. Identify which stage you're in and follow its rules.

Plan → Execute → Validate → Commit
↑                               |
└── fix ────────────────────────┘

1. **Plan** — Understand the task, research code, design approach. Be concise; list unresolved questions.
2. **Execute** — Implement changes AND write tests together. No implementation is complete without tests.
3. **Validate** — ALL checks must pass with zero errors before moving on:
   - [list validation commands]
     If ANY check fails → return to Execute, fix, re-validate. Pre-existing errors are NOT exempt.
4. **Commit** — Only after Validate passes completely. Never commit with failing checks.

## Detailed Guidance

When working on tasks involving these topics, read the linked doc:

- Topic (`docs/agents/file.md`) — brief routing signal describing when to read this
- Run `/skills` to see available patterns and workflows

分类启发式

判断内容留在根文件还是移入 docs/agents/ 的标准：

智能体无人提醒时会做错？是 → 根；有时 → docs/agents/。
适用于每个任务？是 → 根；否 → docs/agents/。
少于 2 行？是 → 根；任意长度 → docs/agents/。
详细参考？否 → 根；是 → docs/agents/。
流程/工作流？仅四阶段循环 → 根；多步骤 → docs/agents/。

原则

最小根文件：根文件每一行都会在每次对话中消耗 token，只写智能体无人提醒时经常做错的规则。
路由信号：每个链接描述必须明确告诉 Claude 何时读取，要具体，例如“pnpm 约定、ESLint 配置”，而不是只写“工具”。
一层深度：所有文档都从根链接，docs/agents/ 文件之间不互相引用。
用 docs/agents/ 而非 docs/：agents/ 子目录把智能体指令与人类文档分开。

适用场景

用户要求把臃肿的 CLAUDE.md 重构为使用 docs/agents 的渐进式披露结构。
新项目需要建立 CLAUDE.md 与主题文档结构。
已有 CLAUDE.md 需要迁移到分层结构。

限制与故障排查

技能未触发：请求措辞未清晰匹配描述中的触发条件，可用描述中的明确领域/任务关键词改写后重试。
与其他技能冲突：多个已加载技能范围重叠，需说明当前步骤以哪个技能为准并优先应用其工作流。
输出过于笼统：任务输入缺少上下文、约束或目标格式，可补充具体约束（环境、范围、格式、成功标准）后重跑。

关于该技能的收费、价格、平台支持等信息，资料中暂未提供。