spec-rules-init

spec-rules-init — 编码规则生成器

提取项目约定，并生成统一的 coding-rules.md，在实现过程中用作质量门禁。

语言规则

1. 自动检测输入语言 → 使用相同语言输出
2. 日语输入 → 日语输出，使用 references/rules-template.ja.md
3. 英语输入 → 英语输出，使用 references/rules-template.md
4. 明确指定的语言优先（例如，“in English”“日本語で”）

执行流程

步骤 0：初始上下文检查

在进行任何交互之前，执行以下检查：

1. 检查当前目录：

   pwd
   ls -la
   

2. 检测约定文件（尽可能并行执行）：

   # Convention files
   ls CLAUDE.md src/CLAUDE.md AGENTS.md test/CLAUDE.md 2>/dev/null
   ls -d .claude/ 2>/dev/null
   
   # Config files
   ls package.json go.mod requirements.txt Cargo.toml 2>/dev/null
   ls .eslintrc* biome.json tsconfig.json .prettierrc* 2>/dev/null
   

3. 检测现有源代码：

   find . -maxdepth 3 -type f \( -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.go" -o -name "*.java" -o -name "*.rs" \) 2>/dev/null | head -30
   

4. 扫描已安装的技能：

   ls ~/.claude/skills/*/SKILL.md .claude/skills/*/SKILL.md 2>/dev/null
   

5. 检查是否存在现有的 coding-rules.md：

   find . -name "coding-rules.md" -type f 2>/dev/null
   

步骤 1：从约定文件中提取规则

读取检测到的约定文件，并按类别提取规则。

检测目标（按优先级排序）：

文件	要提取的内容	优先级
CLAUDE.md（根目录）	项目级规则	高
src/CLAUDE.md	源代码专属规则	高
AGENTS.md	面向 Agent 的规则	高
.claude/ 内容	项目设置	中
package.json	lint/test 脚本是否存在	中
test/CLAUDE.md	测试专属规则	中
.eslintrc* / biome.json	lint 规则	低
tsconfig.json	TypeScript 严格设置	低
.prettierrc*	格式设置	低

提取类别和关键词：

• 测试标准：“coverage”“test”“spec”“E2E”“カバレッジ”“テスト”
• 代码质量：“lint”“typecheck”“strict”“import”“naming”“命名”
• 错误处理：“try/catch”“Logger”“error”“throw”“例外”
• 文档：“JSDoc”“TSDoc”“@ApiProperty”“comment”“コメント”
• 安全：“secret”“password”“hash”“HTTPS”“ログに出力しない”
• Git：“commit”“branch”“コミットメッセージ”“feature branch”

对于每条提取出的规则，记录：

• 类别（以上 6 类之一）
• 内容（规则文本）
• 严重程度：[MUST]（明确要求）、[SHOULD]（建议）、[MAY]（可选）
• 源文件和行号引用

来自 CLAUDE.md / AGENTS.md 的规则优先级为 1，且默认标记为 [MUST]。

第 2 步：代码库分析

如果存在源代码，请分析代码库以检测隐含约定。 如果未找到源文件（新项目），则完全跳过此步骤。

2a. 目录结构分析：

• 扫描目录树（最多深入 3 层）
• 检测模式：按功能划分（modules/{feature}/）、按层划分（controllers/、services/）、测试与代码共置，还是使用单独的 tests/ 目录

2b. 文件命名约定检测：

1. 收集 src/（或主要源代码目录）下的文件名
2. 对每个名称进行分类：kebab-case、camelCase、PascalCase、snake_case
3. 如果某种模式适用于 60% 以上的文件 → 建议标记为 [MUST]
4. 少数模式 → 建议标记为 [SHOULD] 以统一命名

2c. 库分析：

1. 读取依赖文件（package.json、go.mod、requirements.txt 等）
2. 识别主要库：
   • 框架：NestJS、Next.js、Express、Fastify、Django、Flask、Gin 等
   • 测试：Jest、Vitest、Playwright、pytest 等
   • 验证：Zod、class-validator、Joi 等
   • ORM：Prisma、TypeORM、Drizzle、SQLAlchemy、GORM 等
   • 代码检查工具：ESLint、Biome、ruff、golint 等
3. 添加针对库的最佳实践建议，作为 [SHOULD] 规则
   • 示例：检测到 Prisma → [SHOULD] 所有数据库访问均使用 Prisma Client
   • 示例：检测到 Zod → [SHOULD] 使用 Zod 进行运行时验证

2d. 代码模式分析（如果有代码智能工具可用）：

• 导入风格：相对路径（./）与路径别名（@/）
• 导出风格：命名导出与默认导出
• 正在使用的错误处理模式

2e. 共享工具和库检测：

1. 扫描代码库中的共享工具模块、辅助函数和内部库：
   • 查找名为 utils/、helpers/、lib/、shared/、common/ 的目录
   • 识别频繁导入的内部模块
2. 与依赖文件交叉比对，识别常用库
3. 向用户概述检测到的共享工具和库：

   Detected shared utilities and libraries:
     Internal: utils/logger.ts, lib/validation.ts, helpers/date.ts
     External: Zod (validation), Prisma (DB), date-fns (dates)
   

4. 针对每个检测到的共享工具或库，生成一条 [SHOULD] 规则：
   • 示例：[SHOULD] 使用 lib/validation.ts 进行输入验证
   • 示例：[SHOULD] 使用 Zod 进行运行时验证
   • 示例：[SHOULD] 使用 utils/logger.ts，而不是 console.log
5. 在生成的 coding-rules.md 中添加「共享工具」部分，列出检测到的内容

代码库分析结果的优先级为 Priority 2，并标记为 [MUST]（适用于占比超过 60% 的多数模式）或 [SHOULD]。

第 3 步：已安装技能分析

扫描已安装技能，查找针对特定框架的最佳实践。

3a. 技能检测：

1. 扫描 ~/.claude/skills/（全局技能）
2. 扫描 .claude/skills/（项目技能）
3. 阅读每个 SKILL.md 的 frontmatter 描述和正文

3b. 框架匹配： 将检测到的项目技术栈（来自步骤 1–2）与技能关键词进行比较：

项目技术	匹配关键词
Next.js	next、next.js、vercel、react、RSC、server component
NestJS	nest、nestjs、express、fastify、typescript backend
React	react、hooks、component、jsx、tsx
Go	go、golang、goroutine
Python	python、django、flask、fastapi

3c. 用户确认（如果找到匹配的技能）：

使用 AskUserQuestion：

question: "The following installed skills were detected. Use them for rule extraction?" / "以下のインストール済みスキルが検出されました。ルール抽出に使用しますか？"
header: "Skills"
multiSelect: true
options:
  - "{skill-name} — {description} (Recommended)" / "{skill-name} — {説明}"

3d. 优先级映射：

• 源自技能的规则属于 Priority 3 → 标记为 [SHOULD] 或 [MAY]
• 如果技能规则与 Priority 1 或 2 规则冲突 → 保留较高优先级的规则，并显示警告
• 在 coding-rules.md 中将来源记录为 Source: skill/{skill-name}

3e. 没有匹配的技能： 如果未安装匹配的技能，可选择告知用户：

"Matching skills may be available on skills.sh for your tech stack.
Install and re-run to incorporate best practices."
/ "技術スタックに適合するスキルが skills.sh にある可能性があります。
インストール後に再実行すると、ベストプラクティスを取り込めます。"

第 4 步：交互式对话

4a. 展示提取结果：

按类别显示检测到的规则摘要：

Extraction Results:
  Testing Standards:    {n} rules
  Code Quality:         {n} rules
  Error Handling:       {n} rules
  Documentation:        {n} rules
  Security:             {n} rules
  Git:                  {n} rules
  Total:                {total} rules (Priority 1: {n}, Priority 2: {n}, Priority 3: {n})

如果任何类别的规则数为 0，请突出显示以提醒用户。

4b. 选择输出路径（AskUserQuestion）：

question: "Where to save coding-rules.md?" / "coding-rules.md の出力先は？"
header: "Output"
options:
  - "docs/coding-rules.md (Recommended)" / "docs/coding-rules.md（推奨）"
  - "docs/development/coding-rules.md"

如果用户选择“Other”，接受任何有效的文件路径。

4c. 补充规则（AskUserQuestion）：

对于缺少规则或规则不足的类别，提出有针对性的问题：

question: "Any additional testing rules?" / "テスト基準について追加ルールはありますか？"
header: "Testing"
options:
  - "Require 80%+ coverage (Recommended)" / "カバレッジ80%以上を必須にする"
  - "Specify E2E test patterns" / "E2Eテストパターンを指定する"
  - "No additions needed" / "追加不要"

question: "Commit message language?" / "コミットメッセージの言語は？"
header: "Git"
options:
  - "Japanese only" / "日本語のみ"
  - "English only" / "英語のみ"
  - "Conventional Commits (English)" / "Conventional Commits（英語）"

根据检测到的框架，推荐特定于项目类型的规则。 请参阅参考模板中的 Project-Type Recommendations 部分。

4d. 生成 review_rules.md（AskUserQuestion）：

如果使用了 --with-review-rules（自动生成）或 --no-review-rules（跳过），则跳过。否则，询问：

question: "Generate review_rules.md alongside coding-rules.md?" /
          "coding-rules.md と一緒に review_rules.md も生成しますか？"
header: "Review Rules"
options:
  - "Yes, generate both (Recommended)" / "はい、両方生成する（推奨）"
  - "No, coding-rules.md only" / "いいえ、coding-rules.md のみ"

第 5 步：检测现有文件并确保幂等性

如果在第 0 步中发现现有的 coding-rules.md：

1. 读取现有文件
2. 同时检查是否存在 review_rules.md：find . -name "review_rules.md" -type f 2>/dev/null
3. 与新提取的规则进行比较（新增、变更、移除）
4. 使用 AskUserQuestion：

   question: "Existing coding-rules.md found. How to proceed?" / "既存の coding-rules.md が見つかりました。どうしますか？"
   header: "Existing File"
   options:
     - "Overwrite" / "上書きする"
     - "Merge differences" / "差分のみマージ"
     - "Cancel" / "キャンセル"
   

5. 如果选择“Cancel”→ 不做任何更改并退出

第 6 步：生成 coding-rules.md

1. 加载适当的参考模板（依据 Language Rules）
2. 按类别填入提取的规则
3. 添加严重性标签：[MUST]、[SHOULD]、[MAY]
4. 为每条规则注明来源
5. 在末尾包含 Sources 摘要表
6. 如果输出目录不存在，则创建该目录
7. 写入文件

第 6.5 步：生成 review_rules.md（如果选择生成）

如果用户在第 4d 步选择“No”，或指定了 --no-review-rules，则跳过此步骤。

输入：生成的 coding-rules.md 内容 + 第 0–2 步获取的项目信息。

流程：

1. 加载审查模板（依据 Language Rules 加载 references/review-template.md 或 references/review-template.ja.md）
2. 从 coding-rules.md 中提取 [MUST] 和 [SHOULD] 规则，并按审查类别汇总：
   • Security → §1
   • Type safety → §2
   • Framework patterns → §3
   • Code quality → §4
   • Testing → §5
3. 根据项目结构生成审查排除模式：
   • 自动生成的文件：**/*.generated.*
   • 锁文件（依据检测到的包管理器）
   • 构建产物：dist/**、build/**
   • 规范：.specs/**
   • ORM 迁移（如果检测到 ORM）：例如 prisma/migrations/**
4. 按模板原样应用模板中的审查输出指南（§7）
5. 按模板原样应用文档更新检查（§8）。模板要求审查者在审查时动态发现文档文件，而不是使用固定列表。
6. 写入与 coding-rules.md 相同的目录：{output_directory}/review_rules.md

第 7 步：更新 AGENTS.md / CLAUDE.md 引用

生成 coding-rules.md 后，在项目约定文件中追加引用。

流程：

1. 检查项目根目录中是否存在 AGENTS.md

2. 检查是否存在 CLAUDE.md（如果它是指向 AGENTS.md 的符号链接，则跳过）

3. 使用 AskUserQuestion：

   question: "Add reference to coding-rules.md in AGENTS.md / CLAUDE.md?" / "AGENTS.md / CLAUDE.md に coding-rules.md の参照を追記しますか？"
   header: "Update"
   options:
     - "Yes, add reference (Recommended)" / "はい、追記する（推奨）"
     - "No, skip" / "いいえ、スキップ"
   

4. 如果获准，则追加到每个文件的末尾（或现有的“Coding Rules”部分之后）：

   英文版本：

   ## Coding Rules
   
   Follow the coding rules in these files during implementation:
   - [{coding_rules_path}]({coding_rules_path}) — Quality rules generated by spec-rules-init
   - [{review_rules_path}]({review_rules_path}) — Review criteria for code review and second opinion
   

   日文版本：

   ## コーディングルール
   
   実装時のコーディングルールは以下のファイルに従ってください:
   - [{coding_rules_path}]({coding_rules_path}) — spec-rules-init で生成された品質ルール集
   - [{review_rules_path}]({review_rules_path}) — コードレビュー・セカンドオピニオン用のレビュー基準
   

   如果未生成 review_rules.md，则省略 review_rules 行。

5. 如果两个文件都不存在 → 显示警告消息后跳过：

   "Warning: No AGENTS.md or CLAUDE.md found. Skipping reference update."
   / "警告: AGENTS.md も CLAUDE.md も見つかりません。参照追記をスキップします。"
   

第 8 步：spec-series 集成提示

生成完成后，告知用户如何与其他 spec-series 技能集成：

"coding-rules.md has been generated. The following spec-series skills now reference it:
- spec-generator: Uses coding-rules.md as design constraints during the design phase
- spec-inspect: Checks [MUST] rules in Check 13 (Project Rule Compliance)
- spec-implement: Uses coding-rules.md as a quality gate during implementation"
/ "coding-rules.md を生成しました。以下の spec-series スキルが参照するようになっています:
- spec-generator: design フェーズで coding-rules.md を設計制約として使用
- spec-inspect: Check 13（プロジェクトルール準拠）で [MUST] ルールをチェック
- spec-implement: 実装時の品質ゲートとして coding-rules.md を使用"

If review_rules.md was also generated, add:

"review_rules.md has also been generated. It will be used by:
- spec-implement: Review gate references review_rules.md
- spec-workflow-init: Workflow review phases reference review_rules.md
- cmux-second-opinion: Uses review_rules.md for second opinion reviews
- GitHub Actions: Can be referenced by claude-review.yml"
/ "review_rules.md も生成されました。以下で活用されます:
- spec-implement: レビューゲートで review_rules.md を参照
- spec-workflow-init: ワークフローのレビュー Phase で参照
- cmux-second-opinion: セカンドオピニオン実行時に参照
- GitHub Actions: claude-review.yml で参照可能"

选项

选项	描述
--force	不经确认覆盖现有的 coding-rules.md
--category <name>	仅为特定类别生成规则（例如 --category testing）
--with-review-rules	同时生成 review_rules.md（跳过确认）
--no-review-rules	不生成 review_rules.md（跳过确认）

错误处理

• 约定文件无法读取：发出警告并跳过该文件，继续处理其余文件

  "Warning: Could not read {filename}. Skipping."
  / "警告: {filename} を読み取れません。スキップします。"
  

• 输出目录不存在：自动创建

  mkdir -p {output_directory}
  

• 写入权限被拒绝：显示错误并建议使用其他路径

  "Error: Cannot write to {path}. Try a different location."
  / "エラー: {path} に書き込めません。別のパスを指定してください。"
  

• 未找到约定文件：回退到仅对话模式

  "No convention files (CLAUDE.md, AGENTS.md, etc.) found. Proceeding with dialogue-only mode."
  / "規約ファイル（CLAUDE.md, AGENTS.md等）が見つかりません。対話のみモードで進みます。"
  

使用示例

# Generate coding rules from project conventions
"Generate coding rules"
「コーディングルールを生成して」

# Create coding-rules.md with forced overwrite
"Create coding-rules.md --force"
「coding-rules.md を作成 --force」

# Extract rules for a specific category
"Extract project rules --category testing"
「テストルールだけ抽出して」

# After generating, re-run to update
"Update coding-rules.md"
「coding-rules.md を更新して」

完成后的操作

生成 coding-rules.md 后，使用 AskUserQuestion 建议后续操作：

question: "Generation complete. What's next?" / "生成完了。次のアクションは？"
header: "Next"
options:
  - "Generate specifications (spec-generator)" / "仕様書を生成する（spec-generator）"
  - "Set up development workflow (spec-workflow-init)" / "開発ワークフローを設定する（spec-workflow-init）"
  - "Done for now" / "完了"