spec-rules-init

spec-rules-init — Coding Rules Generator

Extract project conventions and generate a unified coding-rules.md for use as a quality gate during implementation.

Language Rules

1. Auto-detect input language → output in the same language
2. Japanese input → Japanese output, use references/rules-template.ja.md
3. English input → English output, use references/rules-template.md
4. Explicit override takes priority (e.g., "in English", "日本語で")

Execution Flow

Step 0: Initial Context Check

BEFORE any interaction, execute these checks:

1. Check current directory:

   pwd
   ls -la
   

2. Detect convention files (parallel where possible):

   # 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. Detect existing source code:

   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. Scan installed skills:

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

5. Check for existing coding-rules.md:

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

Step 1: Rule Extraction from Convention Files

Read detected convention files and extract rules by category.

Detection targets (by priority):

File	Content to Extract	Priority
CLAUDE.md (root)	Project-wide rules	High
src/CLAUDE.md	Source-specific rules	High
AGENTS.md	Agent-oriented rules	High
.claude/ contents	Project settings	Medium
package.json	lint/test script presence	Medium
test/CLAUDE.md	Test-specific rules	Medium
.eslintrc* / biome.json	Lint rules	Low
tsconfig.json	TypeScript strict settings	Low
.prettierrc*	Format settings	Low

Extraction categories and keywords:

• Testing Standards: "coverage", "test", "spec", "E2E", "カバレッジ", "テスト"
• Code Quality: "lint", "typecheck", "strict", "import", "naming", "命名"
• Error Handling: "try/catch", "Logger", "error", "throw", "例外"
• Documentation: "JSDoc", "TSDoc", "@ApiProperty", "comment", "コメント"
• Security: "secret", "password", "hash", "HTTPS", "ログに出力しない"
• Git: "commit", "branch", "コミットメッセージ", "feature branch"

For each extracted rule, record:

• Category (one of the 6 above)
• Content (the rule text)
• Severity: [MUST] (explicit requirement), [SHOULD] (recommended), [MAY] (optional)
• Source file and line reference

Rules from CLAUDE.md / AGENTS.md are Priority 1 and default to [MUST].

ステップ 2：コードベースの分析

ソースコードが存在する場合は、コードベースを分析して暗黙の規約を検出します。 ソースファイルが見つからない場合（新規プロジェクト）は、このステップ全体をスキップしてください。

2a. ディレクトリ構造の分析：

• ディレクトリツリーをスキャンします（最大 3 階層まで）。
• パターンを検出します：機能ベース（modules/{feature}/）、レイヤーベース（controllers/、services/）、テストが各機能と同じ場所にあるか、別の tests/ ディレクトリにあるか。

2b. ファイル命名規則の検出：

1. src/（または主要なソースディレクトリ）配下のファイル名を収集します。
2. 各名前を分類します：kebab-case、camelCase、PascalCase、snake_case。
3. 1 つのパターンがファイルの 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] すべての DB アクセスに 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] console.log の代わりに utils/logger.ts を使用する
5. 検出した一覧を、生成する coding-rules.md の「Shared Utilities」セクションに含めます。

コードベース分析の結果は 優先度 2 とし、[MUST]（多数派のパターンが 60% 以上の場合）または [SHOULD] に割り当てます。

ステップ 3：インストール済みスキルの分析

インストール済みスキルをスキャンし、フレームワーク固有のベストプラクティスを確認します。

3a. スキルの検出：

1. ~/.claude/skills/（グローバルスキル）をスキャンします。
2. .claude/skills/（プロジェクトスキル）をスキャンします。
3. 各 SKILL.md のフロントマターの説明と本文を読み取ります。

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. 優先度の割り当て：

• スキル由来のルールは 優先度 3 とし、[SHOULD] または [MAY] にします。
• スキルのルールが優先度 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 にある可能性があります。
インストール後に再実行すると、ベストプラクティスを取り込めます。"

Step 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 のみ"

Step 5: 既存ファイルの検出と冪等性

Step 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」の場合は、変更せずに終了します

Step 6: coding-rules.md を生成する

1. 適切な参照テンプレートを読み込みます（Language Rules に基づきます）
2. 抽出したルールをカテゴリ別に記入します
3. 重要度タグを適用します：[MUST]、[SHOULD]、[MAY]
4. 各ルールの出典を記載します
5. 末尾に Sources の概要表を含めます
6. 出力ディレクトリが存在しない場合は作成します
7. ファイルを書き込みます

Step 6.5: review_rules.md を生成する（選択した場合）

Step 4d で「No」を選択した場合、または --no-review-rules が指定された場合は、この手順をスキップします。

入力：生成された coding-rules.md の内容と、Steps 0～2 のプロジェクト構造情報。

手順：

1. レビューテンプレートを読み込みます（Language Rules に従い、references/review-template.md または references/review-template.ja.md）
2. coding-rules.md から [MUST] と [SHOULD] のルールを抽出し、レビューカテゴリ別に要約します：
   • セキュリティ → §1
   • 型安全性 → §2
   • フレームワークのパターン → §3
   • コード品質 → §4
   • テスト → §5
3. プロジェクト構造に基づき、レビュー対象外パターンを生成します：
   • 自動生成ファイル：**/*.generated.*
   • ロックファイル（検出されたパッケージマネージャーに基づきます）
   • ビルド成果物：dist/**、build/**
   • 仕様：.specs/**
   • ORM のマイグレーション（ORM が検出された場合）：例：prisma/migrations/**
4. テンプレートのレビュー出力ガイドライン（§7）をそのまま適用します
5. ドキュメント更新チェック（§8）をテンプレートのとおり適用します。テンプレートでは、固定リストを使用するのではなく、レビュー時にレビュー担当者がドキュメントファイルを動的に検出するよう指示しています。
6. coding-rules.md と同じディレクトリに書き込みます：{output_directory}/review_rules.md

Step 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 も見つかりません。参照追記をスキップします。"
   

Step 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" / "完了"