code-spec-guardian

项目代码规范守护者 — 分析项目代码规范/风格/UI风格/架构约定，沉淀为分模块、按需加载的规范文件。 在代码生成、修改、Bug修复、Code Review、技术问答等场景中自动加载相关规范片段进行约束。 支持规范自动增量升级，从每轮对话中提取新规范信息并更新对应模块文件。 触发词：「分析项目规范」「查看规范」「按规范写代码」「这个项目用什么风格」「规范检查」「按项目规范修改」「修复这个bug」「帮我改代码」「写一个XX接口/组件/页面」。 当用户的项目工作目录中存在 .code-spec/ 目录时，本 Skill 自动生效。 Project code spec guardian — Analyzes code conventions/style/UI patterns/architecture, distills them into modular, on-demand loaded spec files. Auto-loads relevant specs during code generation, modification, bug fixing, code review, and technical Q&A. Supports auto-incremental evolution by extracting new spec info from each conversation turn. Triggers: "analyze specs", "show specs", "write code per specs", "fix this bug", "help me modify code", "write an API/component/page".

代码规范守护者 | Code Spec Guardian

定位

项目级代码规范的分析器、存储库、执行器。贯穿开发全生命周期，确保每次代码输出都符合项目既有约定。

核心原则

1. 按需加载 — 每次调用只加载相关模块规范，不全量灌入上下文（目标增量 < 2K tokens）
2. 极简路由 — SKILL.md 仅作路由入口，实际规范存储在 references/ 分模块文件中
3. 自进化 — 从对话中持续提取规范信息，增量更新规范文件（详见下方「自进化机制」专节）
4. 用户可控 — 重大变更必须确认，日常增量静默执行

规范存储位置

规范文件存储在项目根目录下的 .code-spec/ 目录：

text

<项目根目录>/
└── .code-spec/
    ├── index.md              # 规范索引（模块清单 + 摘要）
    ├── code-style.md          # 代码风格规范
    ├── ui-style.md            # UI 风格规范
    ├── architecture.md        # 架构规范
    ├── api-spec.md            # API 设计规范
    ├── sql-spec.md            # SQL/数据库规范
    ├── git-spec.md            # Git 规范
    └── _meta.json             # 版本信息 + 更新时间

若 .code-spec/ 不存在，首次使用时自动创建并提示用户先执行「分析项目规范」。

路由决策表

根据用户问题/任务关键词，仅加载对应模块文件：

关键词 / 意图	加载文件	说明
样式/CSS/颜色/字体/间距/组件/布局/响应式/动画	ui-style.md	UI 相关
API/接口/请求/响应/路由/控制器/endpoint	api-spec.md	API 设计
SQL/表/字段/查询/索引/迁移/ORM/数据库	sql-spec.md	数据库
目录/分层/架构/模块/依赖/状态管理/注入	architecture.md	架构
命名/缩进/分号/引号/格式/import/导出	code-style.md	代码风格
分支/提交/Commit/PR/合并/发版	git-spec.md	Git
修Bug/修复/改代码/重构/优化	按文件类型自动判断 → 加载对应模块	见下方规则
写新代码/新增功能/新建接口/新建组件	按任务类型判断 → 加载 1-3 个相关模块	见下方规则

修Bug / 改代码 时的加载规则

1. 读取目标文件路径，根据文件类型推断模块：
   • .vue/.jsx/.tsx/.css/.scss/.less → ui-style.md
   • controller/router/handler 相关 → api-spec.md
   • model/entity/migration/sql 相关 → sql-spec.md
   • 通用代码文件 → code-style.md + architecture.md
2. 若涉及多文件改动，加载涉及的模块（最多 3 个）
3. 若无法判断，仅加载 code-style.md 作为兜底

写新代码时的加载规则

1. 根据任务描述匹配模块：
   • "写一个组件/页面" → ui-style.md + architecture.md
   • "写一个接口/API" → api-spec.md + architecture.md
   • "写一个SQL/查询" → sql-spec.md
   • 通用功能 → code-style.md + architecture.md
2. 最多同时加载 3 个模块，避免上下文膨胀

使用场景

场景	触发方式	行为
分析项目规范	用户说「分析项目规范」	全量扫描项目，生成/覆盖所有规范文件
写新代码	用户要求写新功能/接口/组件	自动加载相关模块规范，按规范生成代码
修改代码	用户要求修改/重构/优化代码	加载对应模块规范，按规范修改
修复Bug	用户要求修复Bug	加载相关模块规范，修复时遵循规范，避免引入新问题
技术问答	用户问项目相关问题	加载相关模块，在回答中引用规范条目
规范纠正	用户纠正了代码风格	自动提取纠正信息，增量更新规范文件
查看规范	用户说「查看规范」	展示索引 + 指定模块内容
重置规范	用户说「重置规范」	清空并重新分析

自进化机制（核心能力）

本 Skill 不是一个静态的规范文档库，而是一个活的规范系统——它在每次对话中持续学习、提炼、进化。

进化触发条件

以下信号出现时，自动触发规范提取与更新：

信号	示例	处理方式
用户明确给出规范	"我们项目用 2 空格缩进"	直接写入对应模块
用户纠正生成代码	"不要用 var，用 const"	提取为命名规范条目
用户偏好表达	"API 返回用下划线命名"	写入 api-spec.md
代码中体现新约定	生成的代码遵循了项目既有模式	自动识别并记录
用户否定规范	"这个不用遵循"	标记为 deprecated

增量更新流程（每轮对话结束前静默执行）

text

对话内容 → 规范信号识别 → 分类到模块 → 读取现有规范 → 对比差异 → 增量写入

1. 信号识别：从对话中识别出潜在的规范信息（命名偏好、风格纠正、架构约定等）
2. 模块归类：将信息匹配到对应模块（code-style / ui-style / architecture / api-spec / sql-spec / git-spec）
3. 差异对比：读取该模块现有规范文件，判断是新增、修改还是冲突
4. 写入策略：
   • 新增条目：追加到模块文件末尾，标注 [auto: YYYY-MM-DD]
   • 修改条目：更新内容，旧条目保留为注释并标记 [deprecated: YYYY-MM-DD]
   • 冲突条目：新旧规范矛盾时，不自动覆盖，标记 [pending-review]，在回复中提示用户
5. 元数据更新：更新 _meta.json 中的版本号和最后更新时间

重大变更确认机制

以下变更视为"重大"，必须向用户确认后才写入：

• ❌ 删除或废弃已有规范条目
• ❌ 修改核心架构约定（如状态管理方案从 Redux 改为 Zustand）
• ❌ 修改 UI 体系（如更换组件库、更改主题色体系）
• ❌ 单次更新涉及 3 个以上模块

确认方式：在对话中展示简洁的变更摘要 diff，询问用户是否确认。

进化时间线示例

text

Day 1: 用户说"分析项目规范" → 全量扫描，生成 6 个模块文件，共 42 条规范
Day 2: 对话中用户纠正"用单引号" → code-style.md 新增 [CODE-07] 引号规范
Day 3: 用户说"API 返回用 camelCase" → api-spec.md 新增 [API-08] 响应字段命名
Day 5: 用户说"换掉 Moment，用 dayjs" → 重大变更，展示 diff 确认 → 更新 architecture.md
Day 7: 规范已积累 58 条，覆盖 6 个模块，AI 写代码越来越贴合项目风格

信号识别优先级

1. 用户显式指令 > 用户直接说出的规范要求（最高优先级）
2. 用户纠正反馈 > 用户对 AI 生成代码的修改意见
3. 代码模式推断 > 从项目代码中自动识别出的约定
4. 隐式偏好 > 用户在多轮对话中一致表现的偏好倾向

执行流程

流程 1：首次分析项目规范

1. 确认项目根目录路径
2. 扫描项目文件结构和关键代码文件
3. 按维度提取规范（代码风格、UI、架构、API、SQL、Git）
4. 生成 .code-spec/ 目录及各模块文件
5. 生成 index.md 索引和 _meta.json 元数据
6. 向用户展示规范摘要

流程 2：日常代码生成/修改/修复

1. 读取 .code-spec/index.md 确认可用规范
2. 根据路由决策表加载相关模块文件
3. 在代码生成/修改/修复过程中应用规范
4. 在回复中适当引用规范条目编号（如 [UI-03]）
5. 对话结束时执行自动升级检查

流程 3：自进化（详见上方「自进化机制」专节）

每轮对话结束前，按自进化机制的流程执行规范增量更新。

规范文件统一格式

每个 .code-spec/*.md 文件遵循：

markdown

# <模块名>规范
> 适用范围: <适用文件/场景> | 最后更新: YYYY-MM-DD

## <子模块名>

### [编号] 规范名称
- 规则描述（不超过 3 行）
- 示例（可选，1 个最小示例）

### [编号] 另一条规范
...

• 单个模块文件不超过 150 行 / 4KB
• 编号格式：模块前缀 + 序号（如 [UI-01]、[SQL-03]、[CODE-05]）
• 每条规范简洁明了，避免冗长解释

_meta.json 格式

json

{
  "version": 1,
  "lastUpdate": "2026-07-28",
  "projectPath": "<项目路径>",
  "modules": {
    "code-style": { "version": 1, "items": 0, "hash": "" },
    "ui-style": { "version": 1, "items": 0, "hash": "" },
    "architecture": { "version": 1, "items": 0, "hash": "" },
    "api-spec": { "version": 1, "items": 0, "hash": "" },
    "sql-spec": { "version": 1, "items": 0, "hash": "" },
    "git-spec": { "version": 1, "items": 0, "hash": "" }
  }
}

注意事项

• 本 Skill 的规范文件存储在项目目录（.code-spec/），不在 Skill 自身目录中
• Skill 自身目录仅包含 SKILL.md 和可选的分析脚本
• 若同时操作多个项目，每个项目各有独立的 .code-spec/ 目录
• 规范文件应纳入 Git 版本控制，便于团队共享