Skip to content

ximing/vital / .claude/skills/ximing-progressive-project

ximing-progressive-project

Verified

把现有项目重构为适合 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)

---
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 模板

# 项目指令

## 项目概览

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

## 全局规则

- ...

## 开发入口

- 构建:...
- 测试:...

## 局部规则导航

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

目录级 CLAUDE.md 模板

# 目录说明

## 这个目录负责什么

- ...

## 放置约束

- 放什么
- 不放什么

## 开发偏好

- ...

推荐布局示例

对典型 monorepo,优先考虑这种布局:

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。”
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 468kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 321kUpdated Claude CodeCodexVerifiedInstall