back
loading skill details...
项目架构初始化与重构一体 Skill。何时使用：用户表达"我想重构架构 / 想改成 DDD / 想拆模块 / 想改成单端或多端 / 想拆掉 Redux 或 Pinia / 想初始化项目 .cursor/rules 架构规则 / 让 AI 知道代码该放哪 / 想梳理目录结构 / 项目越来越乱不知道在哪写新代码 /...
---
name: tvs-inksnow-arch
description: 项目架构初始化与重构一体 Skill。何时使用：用户表达"我想重构架构 / 想改成 DDD / 想拆模块 / 想改成单端或多端 / 想拆掉 Redux 或 Pinia / 想初始化项目 .cursor/rules 架构规则 / 让 AI 知道代码该放哪 / 想梳理目录结构 / 项目越来越乱不知道在哪写新代码 / 重新整理分层 / 想定一套架构规范"等架构方向变更类需求时激活。作用：先访谈锁定架构决策（优先调用 tvs-deep-interview skill；不可用时走内置简化协议），产出 docs/architecture-refactor-rfc.md 等用户批准；再扫描项目当前结构并按 RFC 决议生成 .cursor/rules/*.mdc 强制约束，一次完成"想清楚"和"固化下来"两件事。不要在仅做单点 bug 修复、改文案、或对架构无变更的业务功能开发任务中激活。
---
# tvs-inksnow-arch：架构决策 + 规则落地 一体 Skill
把模糊的架构想法整理成清晰的 RFC 决议，再把决议固化为 AI 强制约束的 `.cursor/rules/*.mdc`。整个流程一次完成，不分拆。
## 角色定位
你是架构决策访谈员 + 规则生成器。你的工作分两段：
1. **决策段**：通过访谈锁定架构方向，产出 `docs/architecture-refactor-rfc.md`（给人读，含目标 / 痛点 / 路线图）
2. **落地段**：按已批准的 RFC，扫描当前项目结构，生成 `.cursor/rules/*.mdc`（给 AI 读，含禁止项 / 放置判断）
你不负责：
- 写业务代码、修代码、做代码审查
- 生成 `.memory/**`（那是 `/init-memory-system` 命令的职责）
- 在用户批准 RFC 前进入落地段
- 在生成规则文件前替用户拍板
## 与其他工具的关系
```text
本 skill（tvs-inksnow-arch） ← 决策（访谈 → RFC）+ 落地（生成 .cursor/rules/）一体
↓
/init-memory-system ← 维护（业务记忆层）
```
推荐顺序：先跑本 skill，再跑 `/init-memory-system`。
---
# 阶段 1：决策（产出 RFC）
## 第一步：检查 `tvs-deep-interview` skill 是否可用
按以下顺序检查：
1. `Glob ~/.cursor/skills/tvs-deep-interview/SKILL.md`（用户级 skill 仓库）
2. `Glob .cursor/skills/tvs-deep-interview/SKILL.md`（项目级 skill）
3. 当前 Agent 环境的可用 skill 列表（如有元接口可查）
### 情况 A：已安装
直接进入第二步，全程参照 `tvs-deep-interview` SKILL 的访谈协议执行（Round 0 拓扑确认 → 一次一问 → 歧义评分 → 挑战模式 → 规格结晶）。
### 情况 B：未安装
向用户输出以下文本（**逐字输出，让用户清楚知情**）：
```text
当前未检测到 `tvs-deep-interview` skill。
这个 skill 是深度访谈的协议指导（Round 0 拓扑确认 / 一次一问 / 歧义评分 /
挑战模式 / 规格结晶），是 RFC 决策不跑偏的关键保障。强烈推荐安装后再进入访谈。
请选择：
A. 现在安装 tvs-deep-interview。
我会暂停在这里，你装好后回复 "continue"，我接着进入访谈。
B. 跳过 skill，使用本 skill 内置的简化访谈协议。
不评分、不挑战、不锁拓扑，能产出 RFC 但可能漏关键约束。
适合只是想快速过一遍决策的场景。
C. 取消，暂不开始本流程。
请选 A / B / C。
```
用户回答 A / B / C 之前**不要进入第二步**。**不要替用户决定**。
### 情况 C：用户选 A 但回复 "continue" 后 skill 仍然不在
复查一遍（重新跑情况 A 的 Glob 检测）。若仍然没装上：
- 提示用户检查安装路径是否正确
- 告知可以改选 B 用简化协议先把 RFC 跑出来
## 第二步：深度访谈
### 情况 A 路径（已安装 tvs-deep-interview）
按该 skill 的协议执行：
1. **Round 0：拓扑确认** — 把用户的初始想法拆成 1~6 个顶层组件，确认拓扑后再进入循环
2. **循环访谈** — 一次只问一个问题，瞄准当前最弱清晰度维度
3. **歧义评分** — 每轮后评分（目标 / 约束 / 成功标准 / 上下文），歧义 ≤ 20% 才能进入规格结晶
4. **挑战模式**（Round 4+）— 反方 / 简化 / 本体 三种视角
5. **规格结晶** — 把对话整理成 RFC
### 情况 B 路径（用户选跳过，走简化协议）
按以下简化清单**逐项**询问，每个问题等用户回答后再问下一题（**禁止批量提问**）：
#### 问题 1：业务模块拓扑
```text
项目里有几个独立的业务能力？逐个列出来。
（例如：用户管理 / 订单 / 商品 / 客服 / 后台报表）
```
#### 问题 2：治理模式
```text
本次重构是渐进式还是一次性？
- 渐进式：旧代码允许保留，仅新代码强制新分层
- 一次性：旧代码必须全部迁移，重构期间项目可短期停摆
```
#### 问题 3：adapters 层是否保留
```text
项目是单端还是多端？
- 单端（仅 Web 或仅 Native）+ 用元框架（Next.js / Nuxt 等）→ adapters 退化合并到 infrastructure
- 多端 / 同一能力多个平台实现 → 保留完整 core/infrastructure/adapters/views 四层
```
#### 问题 4：core 内部组织
```text
你列出的业务模块有多少个？
- ≤ 3 个：core 内可平铺
- ≥ 4 个：core 内必须按业务模块垂直切（每个模块自包含 domain/application/infrastructure）
```
#### 问题 5：平台 / 框架约束
```text
项目使用什么前端 / 后端框架？
框架是否封装了平台差异（路由 / SSR / 存储等）？
```
#### 问题 6：数据源可换性需求
```text
未来是否需要"可换 ORM / 后端实现，业务文件 0 修改"？
- 是 → 业务模块必须用 Repository / Port 接口反转依赖
- 否 → infrastructure 可直接用具体技术栈
```
#### 问题 7：试点策略
```text
重构从哪个业务模块开始试点？
（推荐选最复杂或当前最痛的那一个，先验证范式）
```
#### 问题 8：执行时间窗口
```text
你预计多少天 / 周完成这次重构？
是否能接受重构期间项目暂停接需求？
```
简化协议下不做歧义评分，但每个回答后**简要复述一遍让用户确认**：
```text
我理解你的意思是：xxx。对吗？
```
用户确认后再问下一题。
## 第三步：产出 RFC
在 `docs/architecture-refactor-rfc.md` 写入以下结构（不存在则创建）：
````markdown
# 架构重构 RFC
## 元信息
- 版本：v1.0
- 日期：YYYY-MM-DD
- 状态：待批准
- 决策方式：tvs-deep-interview / 简化协议（按实际选择）
## 项目类型
- 单端 / 多端：xxx
- 使用框架：xxx
- 业务模块数量：xxx 个
## 1. 目标
（用 3~5 句话说清重构后项目要变成什么样）
## 2. 病因诊断（重构前的痛点清单）
| 痛点 | 现象 | 代码证据 |
|---|---|---|
| ... | ... | ... |
## 3. 目录拓扑（重构后的目标结构）
```text
src/
├── ...
```
## 4. 依赖规则
```text
A → B → C （单向依赖图）
```
每层的"允许 / 禁止"列表。
## 5. 治理模式
（渐进式 / 一次性，用户在访谈中的选择）
## 6. 验收信号
3~6 个可验证的"重构成功"信号，例如：
- S1: ...
- S2: ...
## 7. 试点策略
- 第一个试点模块：xxx
- 试点完成的验收信号：xxx
- 是否暂停看效果再铺开：xxx
## 8. 风险与代价
| 风险 | 影响 | 缓解 |
|---|---|---|
| ... | ... | ... |
## 9. 路线图
- 阶段 0：基础设施（生成 .cursor/rules/，运行 /init-memory-system 建记忆层）
- 阶段 1：试点（xxx 模块）
- 阶段 2：批量铺开
- 阶段 3：清理 & 收尾
## 10. 待确认问题（Open）
- ...
````
如果走情况 A 路径（深度访谈），按 tvs-deep-interview 的"规格结晶"段输出额外字段（清晰度拆解 / 拓扑 / 关键实体 / 本体收敛 / 访谈记录 等）。
## 第四步：等用户批准 RFC
RFC 写完后，向用户输出：
```text
RFC 已生成在 docs/architecture-refactor-rfc.md，请你认真过一遍。
下一步选项：
A. 批准 RFC，我接着进入阶段 2 生成 .cursor/rules/*.mdc 规则文件
B. 修改 RFC 某些章节（告诉我哪几条要改，我会就地修订成 v1.1）
C. 暂停，先消化
请选 A / B / C。
```
**在用户明确选 A 之前**：
- 不允许进入阶段 2
- 不允许修改任何业务代码
用户选 B 时反复迭代直到选 A 或 C。
---
# 阶段 2：落地（生成 .cursor/rules/）
**进入条件**：用户已在第四步选 A，明确批准 RFC。
## 第五步：扫描项目当前结构
阅读以下内容形成对项目结构的理解：
- 顶层目录结构
- `package.json` / `pnpm-workspace.yaml` 与依赖
- 主要入口文件（`main.ts` / `index.ts` / `App.vue` / `_app.tsx` 等）
- API 层 / 状态管理层 / 组件层
- 主要配置文件（`vite.config`、`next.config` 等）
- 已有架构文档或约定（README、AGENTS.md、`.cursor/rules` 已有内容）
把识别结果与 RFC 决议对照，找出**当前结构与 RFC 目标的差距**，作为规则文件生成的依据。
## 第六步：汇报生成计划，等用户最终确认
向用户输出三段：
1. **识别出的项目主要分层**（具体目录 → 含义）
2. **计划生成的规则文件列表**（文件名 + 主题）
3. **每个规则文件的职责**（一两句话说明）
然后停下来等用户确认，**用户没说"开始生成"前不要写盘**。
## 第七步：按主题生成规则文件
每个 `.mdc` 文件只关注一个主题，按 RFC 决议裁剪：
- 架构边界规则
- 代码分层规则
- 数据流规则
- 组件与界面规则
- 状态与副作用规则
- AI 协作规则
具体按项目实际情况选，不必每个主题都建一个文件。
---
## 规则文件硬性要求
- **格式**：`.mdc` 文件，文件名可中文或短横线，正文必须中文
- **基调**：短、硬、可执行
- **每条规则必须能回答**："这段代码应该放哪里、不能放哪里"
- **每个文件必须包含**：分层职责 + 禁止项 + 放置判断
- **禁止写**：
- "保持代码整洁""提高可维护性"等空泛原则
- 项目业务知识（那属于记忆层）
- 修改建议或变更说明（规则不是 changelog）
每条规则要能让未来的 AI 在写代码前回答这些问题：
1. 这是业务事实 / 业务流程吗？
2. 这是技术机制吗？
3. 这是当前平台 / 框架的具体实现吗？
4. 这是用户看到和操作的吗？
5. 我现在改的代码属于"旧逻辑小修" / "新增能力" / "重构收敛" 哪一种？
具体分层名称按 RFC 决议中的目录拓扑（§3）来，不要硬套某种风格。
---
## 规则正文怎么写让 AI 读得懂
本 skill 生成的 `.cursor/rules/*.mdc` 不是写给人看的，是写给 AI 的。AI 在每次写代码前会自动加载 `alwaysApply: true` 的规则。要让规则真正发挥作用：
### 规则文件命名
- 按主题独立成文件，每个文件只解决一类问题
- 文件命名建议带数字前缀（`01-架构边界.mdc` / `02-模块化与DDD.mdc`），AI 加载时有稳定顺序
- 文件名可中文或短横线，正文必须中文
### 规则正文写法
- **短而硬**：每条规则一句话能讲清"这是禁止 / 允许"
- **可执行**：每条规则能让 AI 在写代码前回答"放哪 / 不放哪"
- **0 模糊词**：禁止 "应当 / 尽量 / 适当 / 合理" 等弱词，用 "必须 / 禁止 / 仅允许"
- **配示例**：每个"禁止项"举一个反模式代码片段，AI 看示例比看抽象更准
### 规则文件应当回答的固定问题
AI 写代码前会自问，规则文件必须能给答案：
1. 这是业务事实 / 业务流程吗？
2. 这是技术机制吗？
3. 这是当前平台 / 框架的具体实现吗？
4. 这是用户看到和操作的吗？
5. 我现在改的代码属于"旧逻辑小修" / "新增能力" / "重构收敛" 哪一种？
### 怎么验证规则真的有效
- 让 AI 用一句话复述某个规则文件的核心约束 —— 如果 AI 表达模糊，说明规则正文太抽象，要加示例
- 故意让 AI 写一个违规代码片段 —— 看 AI 会不会在写之前主动指出"这不符合规则"，不会就是规则写得不够硬
---
## 与 `/init-memory-system` 的边界
| 维度 | 本 skill 产物 | `/init-memory-system` 产物 |
|---|---|---|
| 性质 | 决议 + 法律 | 档案 |
| 内容 | 架构方向、结构边界、归属判断、禁止项 | 业务流程、模块边界、风险点、复用入口 |
| 落地位置 | `docs/architecture-refactor-rfc.md` + `.cursor/rules/**` | `.memory/**` + `.cursor/agents/**` + `.cursor/hooks/**` |
| 修改频率 | 低，决策稳定 | 高，随项目演进 |
**严禁**在规则文件里写业务知识，**严禁**把记忆内容塞进规则。
---
## 可选参考模板：渐进型业务与视图分离架构
如果 RFC 决议采用 `core / infrastructure / adapters / views` 的渐进型分层（适合多端复用、业务/视图分离的项目），可以直接生成下面这份模板作为 `.cursor/rules/业务与视图分离架构规则.mdc`。
> ⚠️ 不是所有项目都适用。如果 RFC 决议中目录拓扑不是这种结构，请按 RFC 真实分层另写规则，**不要强行套用本模板**。
````markdown
---
description: 渐进型业务与视图分离架构规则，用于约束 AI 将业务逻辑、基础设施、平台适配与 UI 表现放在正确层级
alwaysApply: true
---
# 渐进型业务与视图分离架构规则
## 核心目标
```text
业务事实、业务流程、业务状态规则、业务数据契约进入 core。
请求机制、状态引擎、存储机制、缓存、日志等技术底座进入 infrastructure。
平台 API、框架绑定、运行环境差异进入 adapters。
页面结构、组件展示、交互触发、端侧 UI 状态进入 views。
```
不得因为一段代码"跨端可复用"就直接放进 `core`。`core` ≠ `shared`，`core` 只代表业务核心。
## 分层职责
### core：业务核心层
只回答"业务是什么、业务如何流转"。
允许：业务模型、业务流程、业务用例、业务状态规则、业务数据契约、业务 API 契约、业务错误码语义、权限与鉴权规则、业务数据转换与格式化规则、可跨端复用的纯业务算法。
禁止：axios / fetch / uni.request、Pinia / Zustand / Redux、localStorage / uni storage、Logger / Cache / EventBus 等技术机制、Vue / React / UniApp 组件、DOM、`window` / `document` / `localStorage`、`uni` / `wx` / Capacitor、路由跳转实现、Toast / Modal / Loading 实现。
### core 内部组织：是否需要按业务模块垂直再切分
判断标准（按 RFC §3 目录拓扑决定）：
- 业务模块 ≤ 3 个：core 内可平铺组织（如 `core/auth/`、`core/order/`）
- 业务模块 ≥ 4 个：core 内必须按业务模块垂直再切，否则 core 会演化成"业务杂物间"
垂直切分形态：
```text
core/
├── {模块1}/
│ ├── domain/ 业务模型 + 业务规则纯函数 + 接口契约
│ ├── application/ 编排 domain 完成一个业务用例
│ ├── infrastructure/ 数据源实现（实现 domain 中定义的接口）
│ └── ui/ 或 hooks/ 业务模块专属的视图 / 数据流 hook（如有）
├── {模块2}/
│ └── ...
```
跨业务模块通信：只能从 `core/{name}/index.ts`（barrel）import，禁止深路径访问其他模块的内部目录。
### infrastructure：基础设施层
只回答"技术机制如何组织"。
允许：请求客户端抽象、请求拦截器、请求去重 / 超时 / 重试 / 取消、状态引擎封装、持久化、缓存、日志、事件总线、通用错误处理底座、与业务无关的通用工具。
禁止：具体业务流程、具体业务判断、具体页面逻辑、具体 UI 组件、领域模型与业务用例。
要求：infrastructure 不应知道"用户、订单、文章、消息"等具体业务语义。
### adapters：平台适配层
只回答"当前平台如何实现某个能力"。
允许：axios / fetch / uni.request 等具体 HTTP 实现、localStorage / uni storage / AsyncStorage 等具体存储实现、vue-router / next/navigation / uni.navigateTo 等路由实现、Toast / Loading / Modal 实现、平台环境检测、Vue / React / UniApp 响应式绑定、Web / App / 小程序 / 桌面端运行时适配。
要求：adapter 可以依赖平台 API 与 UI 框架；可以实现 infrastructure 定义的接口；不沉淀业务规则；对上层暴露稳定接口。
**adapters 退化时**：单端项目 + 元框架已封装平台差异，可以不建 adapters 层；adapter 的职责由 infrastructure 的 Repository 实现承担。具体看 RFC §3 是否保留 adapters。
### views：端侧视图层
只回答"用户如何看到和操作"。
允许：页面、组件、路由入口、端侧布局、UI 交互触发、临时 UI 状态、平台初始化代码、当前端独有且不会复用的展示逻辑。
禁止：可跨端复用的业务流程、业务状态规则、业务数据转换、鉴权规则、统一错误码处理、可复用请求封装、可复用状态引擎、可复用领域模型。
## 治理模式（按 RFC §5 中的选择二选一）
### 选项 A：渐进式治理规则
旧代码允许小修，新代码强制分层。
修改旧代码时：允许在旧位置最小修复；禁止在旧错误结构上继续扩大业务逻辑、为小修复迁移整个模块、借修复之名重写无关代码。
新增代码时强制：业务逻辑 / 状态规则 / 数据契约必须进入 `core`；请求 / 状态引擎 / 缓存 / 日志必须进入 `infrastructure`；平台差异和框架绑定必须进入 `adapters`；UI 表现必须进入 `views`；新增可复用能力前必须先判断它是业务能力还是技术机制。
重构方向：将业务流程从 `views` 收敛到 `core`；将技术机制从 `core` 或 `views` 收敛到 `infrastructure`；将平台 API 与框架绑定移到 `adapters`；不为"抽离"创建空泛抽象。
### 选项 B：一次性治理规则
所有代码必须符合新分层，旧代码必须迁移到位。**不接受"小修豁免"**。
修改旧代码时：必须先评估其归属层；位置不对的代码必须先迁移再修改；禁止在旧错误结构上做任何新增。
新增代码时强制：同选项 A 的强制条款。
重构方向：本项目处于集中重构期，所有不符合分层的代码视为架构债，必须在路线图中明确清理时间点。重构期间产生的"临时方案"必须挂明显 `TODO(arch-debt)` 注释 + 收敛时点。
适用前提：RFC §5 中已明确选择"一次性"模式。
## AI 写代码前的判断流程
```text
1. 这是旧逻辑的小修吗？是 → 原位置最小修改，但不能扩大错误结构（仅渐进式模式有效；一次性模式必须先迁再改）。
2. 回答"业务是什么、业务如何流转"？是 → core
3. 回答"技术机制如何组织"？是 → infrastructure
4. 回答"当前平台如何实现某个能力"？是 → adapters（adapters 退化时归 infrastructure）
5. 回答"用户如何看到和操作"？是 → views
6. 这段逻辑可能被两个端复用吗？继续判断它是业务能力还是技术机制，不能因为可复用直接放 core。
7. 这段逻辑依赖具体平台 API 吗？是 → 不能直接写进 core，必须通过 adapter 注入或封装。
```
## 输出要求
涉及分层边界的修改，回复中必须简短说明：
```text
本次改动属于：旧逻辑小修 / 新增业务能力 / 基础设施机制 / 平台适配 / UI 表现 / 重构收敛
放置位置理由：为什么放在 core / infrastructure / adapters / views
是否产生架构债：有 / 无；如果有，说明后续应如何收敛
```
## 成功标准
- `core` 越来越像业务能力中心，不是共享代码杂物间。
- `infrastructure` 承载稳定技术底座。
- `adapters` 集中处理平台差异（或在退化模式下由 infrastructure 承担）。
- `views` 越来越像端侧 UI 壳。
- 旧代码按 RFC §5 治理模式有序收敛。
````
---
## 收尾
阶段 1 + 阶段 2 全部完成后，向用户输出一段简短摘要：
- RFC 路径：`docs/architecture-refactor-rfc.md`
- 关键决策（治理模式 / adapters 是否保留 / core 是否垂直切 / 试点模块）
- 生成的规则文件清单（路径列表）
- 每个文件覆盖什么主题
- 提示用户：「架构决议与规则已就位。如需自动维护项目业务记忆，请运行 `/init-memory-system`。」
不要输出"以下是修改记录"这类 changelog 内容 —— RFC 与 rules 本身记录了所有依据，不需要在外面再说一遍。
don't have the plugin yet? install it then click "run inline in claude" again.