ximing/vital / .claude/skills/ximing-progressive-project
ximing-progressive-project
Verified把现有项目重构为适合 Claude Code 的持久化指令渐进式加载架构。用户提到“拆分根 CLAUDE.md”、“按目录下沉规则”、“给当前项目设计分层指令文件”、“创建不同目录的 CLAUDE.md”、“补 `.claude/rules`”、“把仓库改造成渐进式加载”时使用。技能默认不仅解释加载机制,还会基于仓库结构直接设计并落地最合适的指令文件布局。
渐进式项目指令架构
目的
本技能不是单纯解释 Claude Code 如何加载指令。
本技能的默认目标是:
- 识别当前仓库的结构与目录职责
- 判断哪些规则应该放在根级、目录级、路径级
- 将项目重构为最合适的渐进式加载架构
- 创建或改写合适的
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.mdCLAUDE.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.tssrc/**/*.tsxpackages/*/src/**/*.tsdocs/**/*.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
只有当这些目录有稳定编辑规范时才建规则;否则保持依赖根说明即可。
示例、产物、镜像目录
以下目录通常不值得建局部规则:
distcoveragebuild- 自动生成目录
- 第三方镜像目录
- 临时实验目录
标准执行流程
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:设计目标布局
默认优先产出如下三层:
- 根
CLAUDE.md - 少量高价值的嵌套
CLAUDE.md - 少量带
paths的.claude/rules/*.md
Step 4:重写根 CLAUDE.md
根文件应做到:
- 能让首次进入仓库的 Claude 快速理解项目
- 不携带大段局部规范
- 明确指出哪些子系统有自己的规则
- 明确指出哪些横切规则通过
.claude/rules加载
Step 5:下沉局部 CLAUDE.md
只给高价值目录创建局部规则,例如:
apps/web/CLAUDE.mdpackages/logger/CLAUDE.mdreactive-state/react/CLAUDE.mdsrc/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:验证加载行为
至少验证:
- 根规则是否足够短且全局化
- 局部规则是否只放在真正会进入的目录
- Claude Code 的路径规则是否带
paths - 导入是否没有破坏懒加载目标
- 如果可用,
/memory中的已加载文件是否符合预期
输出与落地要求
如果用户让你“改项目”,默认直接落地文件,并在汇报时给出:
- 新的规则布局
- 每个新增或更新文件的职责
- 为什么这些目录值得有局部规则
- 哪些目录故意不建规则,以及原因
- 仍存在的不确定点或后续可继续拆分的区域
不要只给抽象建议;能改就改。
文件模板
根 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。”
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 468k | Updated | Claude CodeCodex | Verified | Install |
| 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: 321k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |