code-spec-guardian

Code Spec Guardian

核心原则

1. 按需加载 — 只加载相关模块，目标 < 2K tokens
2. 模型分析 — 规范提取用 AI 语义理解，不由脚本正则匹配
3. 自进化 — 对话中持续提取规范增量更新
4. 多语言 — 自动检测项目语言，路由到对应分析指引

路由决策

触发词 → 模块

语言 → 分析指引

TypeScript：不是独立检测结果，包含在 node 语言下。读 analyze-code-style.md 中的 TS 部分。 如果 project_context.json → configs 中有 tsconfig.json，额外关注 TS 配置。

语言检测由 project_context.json 中的 languages 字段给出（数组，支持多语言）。

首次分析项目规范

⚠️ 开始前 — 安抚用户

首次分析会逐模块进行，需要一些时间。开始前先告知用户：

好的，我来分析这个项目的代码规范。会逐个模块进行（代码风格 → UI → 架构 → API → SQL → Git）， 大约需要几分钟。开始后我会同步播报进度。

流程

1. 运行脚本（快速）：

   python3 {skill_path}/scripts/analyze_project.py 
   

   输出 project_context.json，含语言检测 + 配置文件片段。 进度播报：告知用户检测到的语言和框架。

2. 读入 JSON，确认 languages 和 frameworks

3. 逐个模块分析。每个模块三个动作： a. 读 references/analyze-{module}.md → 获取分析维度 b. 读 references/{module}.md → 获取输出模板 c. 从源码中抽样提取证据 → 写入 .code-spec/{module}.md 每完成一个模块，播报格式：

   ✅ 代码风格规范（25条）— 已完成 🔍 正在分析 UI 风格规范...

4. 如果检测到多个语言，逐个读对应 analyze-{lang}.md（分析指引）和 references/{lang}-style.md（输出模板）， 分析完成后写入 .code-spec/{lang}-style.md（如 python-style.md）， 不要写入 code-style.md

5. 完成播报：

   🎉 全部完成！已生成 N 个规范文件到 .code-spec/，覆盖 N 条规范。 之后写代码/改代码时会自动加载相关规范。

6. 写入 .code-spec/index.md 汇总索引 + 更新 .code-spec/_meta.json（项目规范元数据：条目数/版本/哈希）

首次调用后 — 写入 AGENTS.md 自动触发规则

目的：.code-spec/ 只是静态文档，IDE 不会在写代码时自动加载本 skill。 为了让之后每次写/改代码都自动按规范来，应在 AGENTS.md 固化一条「写代码前触发本 skill」的规则 （AGENTS.md 每次会话都会注入系统提示，是当下最可靠的常驻触发器）。

完成首次分析、生成 .code-spec/ 后，默认帮用户加上这条触发规则，并用温和口吻告知原因、留出口：

规范已经生成到 .code-spec/ 啦～不过它目前只是静态文档，IDE 不会在你写代码时自动加载。 为了让以后每次写/改代码都自动按规范来，我建议把这个 skill 的触发规则写进 AGENTS.md （它每次会话都会自动加载，相当于常驻触发器）。我默认已经帮你加上了，如果你不想加、或想调整措辞，告诉我就好。

执行逻辑：

• 检测 /AGENTS.md 是否存在：

  • 不存在 → 新建 AGENTS.md，写入标题 # AI Rules + 该触发规则小节
  • 已存在 → 先检查是否已含本规则关键词（如 code-spec-guardian / .code-spec）；未含则在「AI 助手指南 / 规范 / 规则」类小节中追加，避免重复

• 默认执行：除非用户明确表示不要，否则直接写入，不阻塞等待确认

• 写入的触发规则文案（按项目实际源码目录调整 src/ 占位）：

  写/改代码前若当前环境的可用 skill 列表中存在 code-spec-guardian，必须先调用它（即 use_skill code-spec-guardian）（若没有安装，则跳过即可）：凡涉及写或修改源代码（如 src/、对应语言源码目录）下代码（api、views、store、utils、components、composables、hooks、types 等），由其按 .code-spec/index.md 路由表加载相关规范模块（每次最多 3 个）并严格按 SOP 产出。该 skill 沉淀的 .code-spec/ 为项目权威规范，优先级高于本文件中的通用约定，冲突以 .code-spec 为准。

注：本环节仅在「首次分析」完成后执行一次；后续「日常使用 / 重新分析」流程不重复询问，除非用户主动要求。

分析指引索引

语言特有输出模板：python-style.md / java-style.md / go-style.md / node-style.md / php-style.md / rust-style.md

日常使用

1. 检测 .code-spec/ 是否存在：用 exec 检查 /.code-spec/index.md 是否存在
   • 存在 → 继续步骤 1
   • 不存在 → 提示用户是否进行首次分析（跳转「首次分析项目规范」流程）
2. 读 .code-spec/index.md 确认已有规范
3. 按路由表加载相关模块（最多 3 个）
4. 应用规范到代码生成/修改/修复/Review
5. 对话结束前检查是否需要自进化
6. （可选）AGENTS.md 触发规则提醒：对话收尾时，若检测到 /AGENTS.md 未含本 skill 触发规则（关键词 code-spec-guardian / .code-spec），则以约 50% 概率在回答末尾附一句温和提示，建议把触发规则写进 AGENTS.md（沿用「首次调用后」小节的规则文案与温和口吻）。原则：轻量提醒、不打扰——不必每次都提，概率约 50%，且不要阻塞等待确认；用户若感兴趣自行决定是否添加。

重新分析项目规范

当项目重大变更后需要重新生成规范时：

1. 询问用户：全量重新分析，还是只更新指定模块？
2. 全量：备份现有 .code-spec/ 为 .code-spec.bak/，然后走「首次分析」流程
3. 指定模块：只重新分析指定模块，覆盖对应文件，其他文件不动
4. 完成后更新 .code-spec/index.md 和 .code-spec/_meta.json
5. （可选）AGENTS.md 触发规则提醒：同「日常使用」步骤 5 —— 若 AGENTS.md 未含触发规则，以约 50% 概率在收尾时温和提示可添加（不每次都提、不阻塞等待确认）。

规范存储

/.code-spec/ — 不同项目独立，可纳入 Git 版本控制。

自进化

详见 references/evolution.md 和 references/skill-meta.json。