ai-check-template 0.2.0-alpha.0

package/package-templates/ci-examples/README.md

@@ -0,0 +1,134 @@
+# CI Examples
+
+`package-templates` から配布する CI 統合の **example**。本パッケージは特定の CI ツールに縛られないため、各 CI 環境向けの YAML / 設定ファイルを「例」として提供し、利用者は自プロジェクトの CI に合わせてカスタマイズする。
+
+> **ステータス**: v0.1 template set（Phase 1 dogfooding 後に改訂予定）
+
+## ディレクトリ構成
+
+```
+ci-examples/
+├── README.md                   # このファイル
+└── github-actions/
+    ├── ai-check.yml            # direct workflow: full check（push / PR 全体）
+    ├── ai-check-fast.yml       # direct workflow: fast check（PR のみ、軽量）
+    ├── ai-quality-reusable.yml # reusable workflow 本体
+    └── ai-quality-call.yml     # reusable workflow を呼ぶ caller
+```
+
+将来の追加候補（別 SPEC で対応）:
+- `gitlab-ci/` — GitLab CI 用
+- `circleci/` — CircleCI 用
+- `bitbucket-pipelines/` — Bitbucket Pipelines 用
+
+GitHub Actions が最初の対象である理由は、OSS / 個人開発を含む採用率が高く、PR Gate として導入しやすいため。
+
+## どれを使うか
+
+| 方式 | ファイル | 向いているケース |
+|---|---|---|
+| Direct full | `github-actions/ai-check.yml` | まず 1 つの workflow で `pnpm ai:check` を走らせたい |
+| Direct fast | `github-actions/ai-check-fast.yml` | PR push ごとに軽量な `pnpm ai:check:fast` を走らせたい |
+| Reusable | `github-actions/ai-quality-reusable.yml` + `ai-quality-call.yml` | install / check の共通ロジックを 1 か所に寄せたい |
+
+最初の導入は direct workflow が簡単。複数 workflow や複数リポで同じ品質ゲートを共有したくなったら reusable workflow に移行する。
+
+## 思想
+
+本パッケージの設計思想に基づく **AI 内部ループ（fast）+ PR Gate（full）のハイブリッド**構成。
+
+```
+[ローカル開発]                       [CI]
+Claude Code Edit hook ─→ ai:check:fast ─→ ai-check-fast.yml (PR)
+                            (Static + Unit)
+                                ↓
+                          AI 修正ループ
+                                ↓
+              人間が PR push
+                                ↓
+                          ai:check (full) ─→ ai-check.yml (PR + push main)
+                            (+ Diagnostic + E2E)
+```
+
+- **fast** = Static + Unit のみ。AI の Edit ごとに走る軽量チェック
+- **full** = fast + Diagnostic（React Doctor / Knip / Semgrep 等）+ E2E。PR / merge 時の重い検証
+
+詳細な思想は以下を参照:
+- [`../docs/philosophy/formal-name-match.md`](../docs/philosophy/formal-name-match.md) — 形名参同（事前宣言「名」と実測「形」の照合）
+- [`../docs/philosophy/test-pyramid.md`](../docs/philosophy/test-pyramid.md) — Static / Unit / Integration / E2E / DB-RLS / Monitoring の責務分割
+
+## カスタマイズ指針
+
+各 YAML 内のコメントに従って以下を調整する。
+
+### 1. パッケージマネージャ
+
+デフォルトは `pnpm`。他の PM を使う場合は `pnpm/action-setup` を差し替え:
+
+| PM | setup action | install command |
+|---|---|---|
+| pnpm | `pnpm/action-setup@v4` | `pnpm install --frozen-lockfile` |
+| npm | （不要） | `npm ci` |
+| yarn | （Node 24+ では Corepack） | `yarn install --frozen-lockfile` |
+| bun | `oven-sh/setup-bun@v2` | `bun install --frozen-lockfile` |
+
+`actions/setup-node` の `cache:` キーも対応する PM 名に変更する。Reusable workflow を使う場合は `package-manager` input を変更する。
+
+### 2. Node version
+
+デフォルトは `22`。プロジェクトの `.nvmrc` / `engines.node` に合わせて調整。LTS（偶数 major）を推奨。
+
+### 3. reusable workflow inputs
+
+`ai-quality-reusable.yml` は以下の inputs を持つ:
+
+| input | default | 用途 |
+|---|---|---|
+| `package-manager` | `pnpm` | `pnpm`, `npm`, `yarn`, `bun` の install path を選ぶ |
+| `node-version` | `22` | npm / pnpm / yarn 用 Node.js version |
+| `install-command` | 空 | 独自 install command を指定。空なら PM ごとの default を使う |
+| `check-command` | `pnpm ai:check` | 実行する品質ゲート |
+| `working-directory` | `.` | monorepo などでコマンドを実行するディレクトリ |
+| `timeout-minutes` | `30` | job timeout |
+| `upload-ai-check-artifacts` | `false` | `.ai-check/` を artifact upload するか |
+
+例:
+
+```yaml
+jobs:
+  ai-quality:
+    uses: ./.github/workflows/ai-quality-reusable.yml
+    with:
+      package-manager: pnpm
+      node-version: "22"
+      check-command: pnpm ai:check
+```
+
+### 4. 任意ツールの有効化
+
+`pnpm ai:check` の中身（`package.json` scripts）でツールを有効化する。本 YAML 自体は `pnpm ai:check` を呼ぶだけなので、ツール選定は利用者の責任。代表的な構成:
+
+- React / Next.js: TypeScript + ESLint(oxlint) + React Doctor + Knip + Playwright + Semgrep
+- Node CLI: TypeScript + ESLint + Vitest + Knip + Semgrep
+- Pure React: TypeScript + ESLint + React Doctor + Knip + Playwright
+
+### 5. timeout 調整
+
+- `ai-check.yml`: default 30 分。E2E が長い場合は伸ばす
+- `ai-check-fast.yml`: default 10 分。fast の意義を保つため上げない（上げる場合はそもそも fast でない）
+- `ai-quality-reusable.yml`: caller 側の `timeout-minutes` input で調整
+
+### 6. third-party action の version pin
+
+セキュリティ要件が厳しい組織では、major version pin（`@v5`）ではなく SHA pin（`@<commit-sha>`）に変更する。Dependabot 等で自動更新する運用が必要。
+
+## なぜ「example」扱いか
+
+CI ツールごとに syntax が異なるため、本パッケージは **CI 統合を強制しない**。各 CI 向けの YAML / 設定は「出発点としての example」と位置付け、利用者は自プロジェクトの CI に合わせてカスタマイズする。
+
+これは本パッケージの**汎用ファースト原則**に基づく。特定 CI（GitHub Actions 等）に強く依存した設計を全利用者に強制せず、思想（形名参同 / 責務分割 / ハイブリッドループ）の方を共有する。
+
+## 出典
+
+- Notion ページ: `c3e549660ca44005a20c4f6fdb54c8d5` — 無料で作る AI エージェント開発診断フロー（参照日 2026-05-13）の「## CIに入れるなら」節
+- 一次資料: GitHub Actions 公式 docs（actions/checkout, actions/setup-node, pnpm/action-setup 等）

package/package-templates/ci-examples/github-actions/ai-check-fast.yml

@@ -0,0 +1,49 @@
+# ai-check-fast.yml — fast check workflow（PR のみ、軽い検証）
+#
+# 配布される example。本リポ自身用ではなく、利用者がコピーして自プロジェクトの
+# .github/workflows/ に配置して使うことを想定。
+#
+# 思想:
+#   - Edit hook（fast）と同じセットを CI でも実行し、AI 内部ループと PR Gate を同期
+#   - Static check + Unit test までに限定（Integration / E2E / Diagnostic は `ai-check.yml` 側）
+#   - PR push のたびに走るため timeout は短く保つ（10 分以内目安）
+#
+# Edit hook との同期:
+#   - Claude Code の Edit hook で `pnpm ai:check:fast` を実行する設定と同じスクリプトを呼ぶ
+#   - 詳細は package-templates/.claude/settings.hook-fragment.json（別 SPEC で提供予定）
+#
+# カスタマイズ可能箇所:
+#   1. パッケージマネージャ・Node version（ai-check.yml と同様）
+#   2. timeout — fast の意義を保つため 10 分以内推奨
+
+name: AI Check (Fast)
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  ai-check-fast:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      # ai:check:fast は package.scripts.fragment.json で定義する軽量スクリプト
+      # 例: "ai:check:fast": "pnpm typecheck && pnpm lint && pnpm test:unit"
+      - name: Run ai:check:fast
+        run: pnpm ai:check:fast

package/package-templates/ci-examples/github-actions/ai-check.yml

@@ -0,0 +1,58 @@
+# ai-check.yml — full check workflow（push / PR 全体）
+#
+# 配布される example。本リポ自身用ではなく、利用者がコピーして自プロジェクトの
+# .github/workflows/ に配置して使うことを想定。
+#
+# 思想:
+#   - 形名参同（formal-name-match.md）: 事前宣言した「名」と実測「形」を CI で照合
+#   - PR Gate（full）= Edit hook（fast）と対をなすハイブリッド構成の片方
+#   - 重い検証（React Doctor / Knip / Playwright / Semgrep 等）は本 workflow に集約
+#
+# カスタマイズ可能箇所:
+#   1. パッケージマネージャ（pnpm / npm / yarn / bun）— `pnpm/action-setup` を差し替え
+#   2. Node version — `node-version` を変更
+#   3. timeout — プロジェクトの E2E 等の重さに応じて調整
+#   4. artifact upload — diagnostic ログを残したい場合は末尾コメント部を有効化
+
+name: AI Check
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  ai-check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v5
+
+      # パッケージマネージャは利用プロジェクトに合わせて差し替え可
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      # ai:check は package.scripts.fragment.json に定義する統合スクリプト
+      # 例: "ai:check": "pnpm typecheck && pnpm lint && pnpm test && pnpm test:e2e:smoke"
+      - name: Run ai:check
+        run: pnpm ai:check
+
+      # 形名照合の結果を artifact として保存する場合（オプション）:
+      # - name: Upload diagnostic logs
+      #   if: always()
+      #   uses: actions/upload-artifact@v4
+      #   with:
+      #     name: ai-check-logs
+      #     path: .ai-check/

package/package-templates/ci-examples/github-actions/ai-quality-call.yml

@@ -0,0 +1,26 @@
+# ai-quality-call.yml — caller workflow for ai-quality-reusable.yml
+#
+# Copy both files into your project's .github/workflows/ directory:
+#   - ai-quality-reusable.yml
+#   - ai-quality-call.yml
+#
+# The caller stays small while the reusable workflow keeps the install/check
+# details in one place.
+
+name: AI Quality
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  ai-quality:
+    uses: ./.github/workflows/ai-quality-reusable.yml
+    with:
+      package-manager: pnpm
+      node-version: "22"
+      check-command: pnpm ai:check

package/package-templates/ci-examples/github-actions/ai-quality-reusable.yml

@@ -0,0 +1,113 @@
+# ai-quality-reusable.yml — reusable workflow for ai:check
+#
+# Copy this file into .github/workflows/ai-quality-reusable.yml in your project.
+# Then call it from a small workflow like ai-quality-call.yml.
+#
+# This is still an example, not a hosted workflow contract. Pin to a released
+# tag when you copy from this repository.
+
+name: AI Quality Reusable
+
+on:
+  workflow_call:
+    inputs:
+      package-manager:
+        description: "pnpm, npm, yarn, or bun"
+        required: false
+        type: string
+        default: pnpm
+      node-version:
+        description: "Node.js version for npm, pnpm, and yarn projects"
+        required: false
+        type: string
+        default: "22"
+      install-command:
+        description: "Optional custom install command"
+        required: false
+        type: string
+        default: ""
+      check-command:
+        description: "Command that runs the project quality gate"
+        required: false
+        type: string
+        default: "pnpm ai:check"
+      working-directory:
+        description: "Directory where install and check commands run"
+        required: false
+        type: string
+        default: "."
+      timeout-minutes:
+        description: "Job timeout"
+        required: false
+        type: number
+        default: 30
+      upload-ai-check-artifacts:
+        description: "Upload .ai-check/ after the run when present"
+        required: false
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+
+jobs:
+  ai-quality:
+    runs-on: ubuntu-latest
+    timeout-minutes: ${{ inputs.timeout-minutes }}
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: pnpm/action-setup@v4
+        if: ${{ inputs.package-manager == 'pnpm' }}
+        with:
+          version: 10
+
+      - uses: oven-sh/setup-bun@v2
+        if: ${{ inputs.package-manager == 'bun' }}
+
+      - uses: actions/setup-node@v5
+        if: ${{ inputs.package-manager != 'bun' }}
+        with:
+          node-version: ${{ inputs.node-version }}
+          cache: ${{ inputs.package-manager }}
+
+      - name: Enable Corepack
+        if: ${{ inputs.package-manager == 'pnpm' || inputs.package-manager == 'yarn' }}
+        run: corepack enable
+
+      - name: Install dependencies with custom command
+        if: ${{ inputs.install-command != '' }}
+        run: ${{ inputs.install-command }}
+        working-directory: ${{ inputs.working-directory }}
+
+      - name: Install dependencies with pnpm
+        if: ${{ inputs.install-command == '' && inputs.package-manager == 'pnpm' }}
+        run: pnpm install --frozen-lockfile
+        working-directory: ${{ inputs.working-directory }}
+
+      - name: Install dependencies with npm
+        if: ${{ inputs.install-command == '' && inputs.package-manager == 'npm' }}
+        run: npm ci
+        working-directory: ${{ inputs.working-directory }}
+
+      - name: Install dependencies with yarn
+        if: ${{ inputs.install-command == '' && inputs.package-manager == 'yarn' }}
+        run: yarn install --immutable
+        working-directory: ${{ inputs.working-directory }}
+
+      - name: Install dependencies with bun
+        if: ${{ inputs.install-command == '' && inputs.package-manager == 'bun' }}
+        run: bun install --frozen-lockfile
+        working-directory: ${{ inputs.working-directory }}
+
+      - name: Run AI quality gate
+        run: ${{ inputs.check-command }}
+        working-directory: ${{ inputs.working-directory }}
+
+      - name: Upload ai-check artifacts
+        if: ${{ always() && inputs.upload-ai-check-artifacts }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: ai-check-artifacts
+          path: ${{ inputs.working-directory }}/.ai-check/
+          if-no-files-found: ignore

package/package-templates/docs/philosophy/formal-name-match.md

@@ -0,0 +1,182 @@
+# 形名参同
+
+> **ステータス**: Draft v0.1（Phase 1 dogfooding 後に改訂予定）
+
+## このファイルの守備範囲
+
+AI 駆動開発における品質担保の中核概念「形名参同」を定義する。事前に宣言する成功基準（「名」）と、実装後の実測値（「形」）を照合する考え方と、AI 駆動開発における適用パターンを扱う。
+
+各層（Static / Unit / Integration / E2E / DB-RLS / Monitoring）への落とし込みは [`test-pyramid.md`](./test-pyramid.md)、観点設計の具体技法は [`qa-techniques.md`](./qa-techniques.md)、Given-When-Then 構文で「名」を表現する方法は [`given-when-then.md`](./given-when-then.md) を参照。
+
+## 概念定義
+
+形名参同（けいめいさんとう）は、**事前に宣言した成功基準（「名」）と、実装後の実測値（「形」）が一致しているか**を機械的に照合する考え方。
+
+AI 駆動開発では、AI が「実装が完了しました」「テストは通っています」と自己申告することが多い。しかし AI 出力は非決定的であり、同じプロンプトでも結果が変わる。さらに「ベンチマーク高得点」と「実運用で壊れない」は同一ではない。
+
+そのため、AI の自己申告を信用せず、**実装前に「何をもって正しいか」を宣言し、実装後にコマンドやテストの実測値と照合する**ことで、品質を担保する。
+
+- **名（めい）**: 実装前に固定する成功基準
+- **形（けい）**: 実装後の実測値（コマンド出力、テスト結果、ログ）
+
+両者が一致したときのみ「実装完了」と判定する。
+
+## 「名」と「形」の対応表
+
+| 「名」（事前宣言） | 「形」（実測値） | 照合手段 |
+|---|---|---|
+| 型エラーが 0 件 | `tsc --noEmit` の終了コード | 0 == 0 ? |
+| lint エラーが 0 件 | lint コマンドの終了コード | 0 == 0 ? |
+| ユニットテスト全 pass | テストランナーの終了コード | 0 == 0 ? |
+| カバレッジが閾値以上 | カバレッジレポート | actual >= threshold ? |
+| 主要導線 E2E pass | E2E テストの終了コード | 0 == 0 ? |
+| 静的解析スコアが閾値以上 | 静的解析ツールのスコア | actual >= threshold ? |
+| 未使用 export が 0 件 | 未使用検出ツールの出力件数 | 0 == 0 ? |
+| 受け入れ条件 AC-XX を満たす | AC-XX の検証コマンド出力 | output == expected ? |
+| セキュリティ High/Critical が 0 件 | SAST ツールの出力 | 0 == 0 ? |
+| API 応答が仕様通り | 契約テストの終了コード | 0 == 0 ? |
+
+「名」が曖昧（「いい感じに動く」「ちゃんと動く」）だと、「形」と照合できない。**「名」は実行可能な検証条件で表す**必要がある。
+
+## AI 駆動開発での適用
+
+形名参同を AI 駆動開発に適用すると、以下のループになる。
+
+```
+1. 人間が「名」を宣言する（成功基準を実行可能な形で定義）
+2. AI が Plan を出す（成功基準を満たすための設計）
+3. 人間が Plan を承認する
+4. AI が実装する
+5. AI が「形」を測定する（事前宣言したコマンドを実行）
+6. AI が「名」と「形」を照合し報告する
+7. 不一致なら AI が修正する
+8. 形 == 名 になるまでループ
+9. 人間が最終承認する
+```
+
+ポイントは:
+
+- **Step 1 の「名」を実装前に固定する**。実装後に成功基準を緩めない
+- **Step 5 で AI に「動きました」と言わせない**。コマンド出力を必ず添付させる
+- **Step 6 で照合表を作る**。「名」「形」「一致/不一致」「未解決リスク」を明示
+
+## 段階的導入
+
+形名参同を一度にすべて導入するのは重い。段階的に進める。
+
+### Phase A: 「名」の宣言を文書化する
+- 実装前に成功基準を Plan に書く
+- 検証は手動でよい
+- 効果: AI と人間の認識ずれが減る
+
+### Phase B: 検証コマンドを定義する
+- 「名」に対応する検証コマンドを併記する
+- 検証は AI が実行し、出力を貼り付ける
+- 効果: 「動きました」の自己申告を排除
+
+### Phase C: 機械的に照合する
+- 統合スクリプト（例: `ai:check`）で一括検証
+- CI に組み込む
+- 効果: 人間の作業を最小化、客観的判定
+
+### Phase D: 不一致時の自動修正
+- 「形」と「名」が不一致のとき、AI に自動修正を指示
+- 修正後に再検証ループ
+- 効果: 修正サイクルを自動化、開発速度向上
+
+各 Phase の昇格基準は組織で決める。例えば「2 週間 Phase A を運用して定着したら B に移行」など。
+
+## 実装パターン
+
+### パターン 1: Plan-First プロンプト
+
+```
+このタスクを実装する前に、まずプランを出してください。
+
+プランには以下を含めてください:
+1. 変更対象ファイル
+2. 実装方針
+3. 成功基準（受け入れ条件）
+4. 実装後に実行する検証コマンド
+5. 想定リスク
+6. 未確認になる項目
+
+まだコードは変更しないでください。
+```
+
+成功基準を**実装前**に固定することで、後付けの正当化を防ぐ。
+
+### パターン 2: 形名照合報告
+
+```
+実装が完了したら、以下の表で報告してください。
+
+| 名（事前宣言） | 形（実測値） | 一致 | 未解決リスク |
+|---|---|---|---|
+| 型エラー 0 | tsc --noEmit 出力 | ✓ / ✗ | - |
+| lint エラー 0 | lint コマンド出力 | ✓ / ✗ | - |
+| AC-01 pass | AC-01 検証コマンド出力 | ✓ / ✗ | - |
+```
+
+口頭の「完了しました」を表に置き換える。
+
+### パターン 3: 統合スクリプト
+
+```bash
+#!/usr/bin/env bash
+# ai-check.sh: 「形」を一括測定して「名」と照合
+set -e
+
+echo "=== Static ==="
+npx tsc --noEmit
+npx <lint-command> .
+
+echo "=== Unit ==="
+npx <test-runner> run
+
+echo "=== Diagnostics ==="
+npx <code-quality-tool>
+npx <unused-detector>
+
+echo "=== E2E (smoke) ==="
+npx <e2e-runner> --grep smoke
+
+echo "All names matched. Implementation passes."
+```
+
+このスクリプトの終了コード 0 = 「形」が「名」と全件一致した状態。
+
+具体的なツール名は対象プロジェクトのプロファイル（`react-nextjs`, `node-cli` 等）で決まる。
+
+## なぜ重要か
+
+AI が「動きました」と申告するだけでは、以下が担保されない:
+
+- 主観的な「動く」と機械的な「動く」のずれ
+- 一部だけテストして全体が動くと誤認
+- カバレッジ範囲外の経路で壊れる
+- パフォーマンス・セキュリティ要件の見落とし
+- 「次回直します」が積み上がる
+
+形名参同は、**人間が確認すべき項目を「名」として固定し、AI に「形」の測定を強制する**ことで、これらの抜けを防ぐ。
+
+## アンチパターン
+
+| アンチパターン | 何が悪いか | 対処 |
+|---|---|---|
+| 名を実装後に書く | 「動いたから良い」と後付け正当化される | 必ず実装前に Plan で固定 |
+| 名を曖昧に書く（「正常に動く」） | 形と照合できない | 検証コマンド + 期待値で表現 |
+| 形を AI の口頭報告で済ます | コマンド実行の証拠がない | 出力ログの貼付を必須化 |
+| 不一致を見逃して名を緩める | 品質基準が劣化する | 不一致時は AI に修正させる |
+| 一部の名だけ照合する | 抜けた検証項目から事故が出る | 統合スクリプトで一括実行 |
+
+## 隣接する思想との関係
+
+- [`test-pyramid.md`](./test-pyramid.md) — 形名参同の「名」を Static / Unit / Integration / E2E / DB-RLS / Monitoring の各層でどう定義するか
+- [`given-when-then.md`](./given-when-then.md) — 「名」を Given-When-Then 構文で記述する具体的な方法
+- [`qa-techniques.md`](./qa-techniques.md) — 「名」に含めるべきテスト観点（同値分割・境界値・デシジョンテーブル等）
+
+## 出典
+
+- Notion ページ: `c3e549660ca44005a20c4f6fdb54c8d5` — 無料で作る AI エージェント開発診断フロー（参照日 2026-05-13）
+- 補強概念: 「形名参同」は中国古典『韓非子』に由来する統治用語（名 = 職務名と、形 = 実際の働きの一致を統治の要とする思想）。本ドキュメントではソフトウェア品質保証の文脈で再解釈している