---
name: ximing-progressive-project
description: 把现有项目重构为适合 Claude Code 的持久化指令渐进式加载架构。用户提到“拆分根 CLAUDE.md”、“按目录下沉规则”、“给当前项目设计分层指令文件”、“创建不同目录的 CLAUDE.md”、“补 `.claude/rules`”、“把仓库改造成渐进式加载”时使用。技能默认不仅解释加载机制，还会基于仓库结构直接设计并落地最合适的指令文件布局。
---

# 渐进式项目指令架构

## 目的

本技能不是单纯解释 Claude Code 如何加载指令。

本技能的默认目标是：

1. 识别当前仓库的结构与目录职责
2. 判断哪些规则应该放在根级、目录级、路径级
3. 将项目重构为最合适的渐进式加载架构
4. 创建或改写合适的 `CLAUDE.md`、嵌套 `CLAUDE.md`、`.claude/rules/*.md`

如果仓库可访问，默认直接分析并改文件，而不是只停留在解释层。

## 适用场景

以下请求应直接使用本技能：

- “帮我把当前项目改成渐进式加载”
- “这个仓库怎么拆 CLAUDE.md 才合理”
- “根据目录职责生成不同的 CLAUDE.md”
- “帮我补 `.claude/rules`”
- “根规则太大了，帮我下沉到子目录”
- “想让 Claude 进入不同目录时加载不同约束”
- "请根据 Claude Code 的持久化指令机制重构项目规则"

## 成功标准

完成后应满足：

- 根 `CLAUDE.md` 足够精简，只保留全局基线
- 子目录规则只在进入对应区域时加载
- 跨目录但可按文件模式命中的规则放到 `.claude/rules/*.md` 并带 `paths`
- 不为每个目录机械生成规则，只覆盖真正有语义边界的区域
- 现有规则体系没有被打散成多个互相冲突的真相源

## 加载模型速记

设计前先基于以下事实判断，不要偏离：

### Claude Code 加载机制

#### 启动时加载

Claude 会从当前工作目录向上加载可见的：

- `CLAUDE.md`
- `CLAUDE.local.md`
- `.claude/CLAUDE.md`
- `.claude/rules/` 中未被更窄作用域限制的内容

#### 按需加载

以下内容只有在 Claude 真正进入相关区域时才加载：

- 子目录中的 `CLAUDE.md`
- 带 `paths` 的 `.claude/rules/*.md`
- 更深层目录中的局部规则

#### 导入不是懒加载

如果根 `CLAUDE.md` 通过 `@...` 导入大段内容，被导入内容会跟着根文件一起进入上下文。

因此：

- `@...` 用于复用与维护
- 不要把它当成主要的渐进式加载机制

## 设计原则

### 1. 根文件只放基线

根 `CLAUDE.md` 只放：

- 仓库级目标与架构概览
- 必须全局生效的工程约束
- 常用构建、测试、提交流程入口
- 指引性说明：更细规则分布在哪些区域

不要把包级、页面级、框架级细节堆在根文件。

### 2. 目录规则只为“稳定语义边界”服务

只有同时满足以下至少两项，才值得单独建局部 `CLAUDE.md`：

- 目录职责稳定
- 会被多人长期触达
- 对文件放置和实现方式有持续约束
- 与父目录相比有明确增量规则

### 3. 路径规则解决横切关注点

如果规则跨多个目录，但能用文件模式描述，就创建 `.claude/rules/*.md`：

- `**/*.test.ts`
- `src/**/*.tsx`
- `packages/*/src/**/*.ts`
- `docs/**/*.md`

Claude Code 的规则文件必须带 `paths`，否则很容易出现启动时广泛加载。

### 4. 不要制造两个真相源

优先沿用仓库现有约定：

- 如果仓库已经用 `CLAUDE.md` + `.claude/rules/*.md`，继续在这套体系内演进
- 如果规则目录下已经存在以 `km-`、`km-web-`、`km-rn-` 为前缀的规则文件，将其视为既有通用知识资产：默认不改写、不迁移、不合并、不删除，项目规则设计只需重点挖掘仓库本身的约束与结构

### 5. 子级规则只能补充，不应推翻父级基线

局部规则的职责是缩小作用域、补充细节、明确放置边界，而不是否定根规则。

## 决策表

| 目标                          | Claude Code 位置               |
| ----------------------------- | ------------------------------ |
| 所有人始终都要看到            | 根 `CLAUDE.md`                 |
| 只有某个子树需要看到          | 该子树下的 `CLAUDE.md`         |
| 横跨多个目录但可由 glob 命中  | `.claude/rules/*.md` + `paths` |
| 当前用户个人、仅当前仓库适用  | `CLAUDE.local.md`              |
| 一次性工作流、不是持久化规则  | skill，不放进 `CLAUDE.md`      |

## 目录识别启发式

分析仓库时，优先按“语义边界”而不是目录层级深度分类。

### 仓库根

通常适合保留：

- 项目概览
- workspace / monorepo 结构说明
- 根命令
- 全局代码质量约束
- 指向下层规则的导航

### `apps/`、`packages/`、`services/`、`modules/`

如果每个子目录是独立产品、包或子系统：

- 给每个稳定子系统一个局部 `CLAUDE.md`
- 内容写该区域独有的约束，不重复根规则

### `src/pages`、`features`、`domains`

如果目录承载页面、业务域或功能分片：

- 页面根目录适合写放置策略与分形组织原则
- 具体页面目录只有在差异足够大时才继续下沉

### `components`、`types`、`utils`、`hooks`

这类共享目录适合写“共享边界”：

- 什么内容才算全局共享
- 页面私有内容应该下沉到哪里
- 不要混入与目录职责无关的业务规则

### `tests`、`__tests__`、`specs`

优先用 `.claude/rules/testing.md` 这类路径规则，而不是给每个测试目录都写 `CLAUDE.md`。

### `docs`、`scripts`、`configs`

只有当这些目录有稳定编辑规范时才建规则；否则保持依赖根说明即可。

### 示例、产物、镜像目录

以下目录通常不值得建局部规则：

- `dist`
- `coverage`
- `build`
- 自动生成目录
- 第三方镜像目录
- 临时实验目录

## 标准执行流程

### Step 1：盘点现状

至少检查：

- 现有 `CLAUDE.md`、`CLAUDE.local.md`、`.claude/rules/*.md`
- 规则目录中是否已有以 `km-`、`km-web-`、`km-rn-` 为前缀的文件；若存在，标记为既有通用资产，默认排除在本次项目规则重构范围之外
- 目录树中哪些区域是真正长期维护的代码区域
- 当前规则是否过于集中、重复、冲突、缺少作用域

输出一个目标清单：
`{ path, kind, current_state, recommended_action, reason }`

### Step 2：识别稳定边界

基于目录名、代表性文件、已有文档与代码组织判断：

- 哪些是仓库级共识
- 哪些是子系统级约束
- 哪些是横切关注点
- 哪些只是临时结构，不值得建规则

判断不清时，优先保守，不要过度拆分。

### Step 3：设计目标布局

默认优先产出如下三层：

1. 根 `CLAUDE.md`
2. 少量高价值的嵌套 `CLAUDE.md`
3. 少量带 `paths` 的 `.claude/rules/*.md`

### Step 4：重写根 `CLAUDE.md`

根文件应做到：

- 能让首次进入仓库的 Claude 快速理解项目
- 不携带大段局部规范
- 明确指出哪些子系统有自己的规则
- 明确指出哪些横切规则通过 `.claude/rules` 加载

### Step 5：下沉局部 `CLAUDE.md`

只给高价值目录创建局部规则，例如：

- `apps/web/CLAUDE.md`
- `packages/logger/CLAUDE.md`
- `reactive-state/react/CLAUDE.md`
- `src/pages/CLAUDE.md`

局部文件应只回答三件事：

- 这个目录负责什么
- 什么该放这里，什么不该放这里
- 在这里改代码时优先遵循什么局部范式

### Step 6：抽横切规则到 `.claude/rules`

以下类型优先使用路径规则：

- 测试文件
- React / Vue / TSX 组件
- API handler
- docs / markdown
- 配置文件

#### Claude Code 最小模板（`.claude/rules/*.md`）

```markdown
---
paths:
  - "src/**/*.tsx"
  - "packages/*/src/**/*.tsx"
---

# React 组件规则

- 导出组件时优先保持接口清晰。
- 共享组件不要耦合页面私有状态。
```

### Step 7：收敛重复与冲突

完成后必须处理：

- 根文件里残留的局部内容
- 子级原封不动重复父级的段落
- `.claude/rules` 没有 `paths` 导致的过宽作用域
- 为了"看起来完整"而机械生成的大量空洞规则文件

### Step 8：验证加载行为

至少验证：

1. 根规则是否足够短且全局化
2. 局部规则是否只放在真正会进入的目录
3. Claude Code 的路径规则是否带 `paths`
4. 导入是否没有破坏懒加载目标
5. 如果可用，`/memory` 中的已加载文件是否符合预期

## 输出与落地要求

如果用户让你“改项目”，默认直接落地文件，并在汇报时给出：

1. 新的规则布局
2. 每个新增或更新文件的职责
3. 为什么这些目录值得有局部规则
4. 哪些目录故意不建规则，以及原因
5. 仍存在的不确定点或后续可继续拆分的区域

不要只给抽象建议；能改就改。

## 文件模板

### 根 `CLAUDE.md` 模板

```markdown
# 项目指令

## 项目概览

- 仓库类型：...
- 关键子系统：...

## 全局规则

- ...

## 开发入口

- 构建：...
- 测试：...

## 局部规则导航

- `packages/logger/` 有自己的 `CLAUDE.md`
- React 组件规则在 `.claude/rules/react-components.md`
```

### 目录级 `CLAUDE.md` 模板

```markdown
# 目录说明

## 这个目录负责什么

- ...

## 放置约束

- 放什么
- 不放什么

## 开发偏好

- ...
```

## 推荐布局示例

对典型 monorepo，优先考虑这种布局：

```text
repo/
├── CLAUDE.md
├── .claude/
│   └── rules/
│       ├── testing.md          # paths: ["**/*.test.ts"]
│       ├── react-components.md # paths: ["src/**/*.tsx"]
│       └── markdown.md         # paths: ["docs/**/*.md"]
├── apps/
│   ├── web/
│   │   └── CLAUDE.md
│   └── admin/
│       └── CLAUDE.md
├── packages/
│   ├── logger/
│   │   └── CLAUDE.md
│   └── core/
│       └── CLAUDE.md
└── shared/
    ├── components/
    │   └── CLAUDE.md
    └── types/
        └── CLAUDE.md
```

## 常见错误

- 把整个仓库的细节都塞进根 `CLAUDE.md`
- 给每个叶子目录都生成一个规则文件
- 用 `@...` 导入大段内容，误以为实现了懒加载
- Claude Code 规则文件没有 `paths`，导致启动时广泛加载
- 把以 `km-`、`km-web-`、`km-rn-` 为前缀的既有规则文件当成项目自身规则去改写、迁移或清理
- 局部规则只是把父级规则再抄一遍

## 默认行为

除非用户明确只想了解概念，否则默认按“分析仓库 -> 设计分层 -> 直接落地文件 -> 汇报原因”的方式执行。

## 示例触发语句

- “请把这个项目重构成适合 Claude Code 的渐进式规则架构。”
- “根据目录功能，帮我创建不同的 `CLAUDE.md` 和规则文件。”
- “根规则太重了，帮我拆成根规则、目录规则和路径规则。”
- “按照 Claude 持久化指令的加载机制改造当前仓库。”
- “检查这个 monorepo 应该在哪些目录放局部 `CLAUDE.md`。”