docs: AI コーディングエージェント共通設定を追加 (#17396)

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-24 13:54:12 +02:00 · 2026-05-12 17:56:06 +09:00
parent b950f905e5
commit f6ea52b1be
28 changed files with 2381 additions and 2 deletions
--- a/.claude/commands/README.md
+++ b/.claude/commands/README.md
@@ -0,0 +1,38 @@
+# `.claude/commands/` — プロジェクト固有のスラッシュコマンド
+
+Misskey 開発で繰り返し使うワークフローを `/command-name` で呼び出せるよう、`.claude/commands/<name>.md` 形式で配置している。
+
+## 実装済みコマンド
+
+### Misskey オリジナル
+
+| コマンド | 用途 | 典型ユースケース |
+| --- | --- | --- |
+| [`/check-misskey-js`](./check-misskey-js.md) | `pnpm build-misskey-js-with-types` を走らせ、`packages/misskey-js/src/autogen/` の差分を報告 | backend の API endpoint を追加・変更した直後 |
+| [`/changelog-add`](./changelog-add.md) | `CHANGELOG.md` の `## Unreleased` 配下、対応するサブセクションに 1 行追記 | ユーザー影響のある変更をコミットする直前 |
+| [`/migrate-new`](./migrate-new.md) | TypeORM `migration:create` の薄いラッパー (拡張子変換 + SPDX 付与 + `check-migrations` で pending DDL 検出) | 手書き SQL / データ移行用に空雛形が欲しい時 |
+
+### ECC ([everything-claude-code](https://github.com/affaan-m/everything-claude-code)) 由来 (MIT)
+
+ECC の MIT ライセンスファイルを Misskey の規約に合わせて再構成したもの。出典は [.claude/THIRD_PARTY_LICENSES.md](../THIRD_PARTY_LICENSES.md) を参照。
+
+| コマンド | 用途 | 典型ユースケース |
+| --- | --- | --- |
+| [`/quality-gate`](./quality-gate.md) | `pnpm lint` + 各パッケージの unit test を順次実行する軽量品質ゲート | 完了前の軽量チェック (重い E2E は CI 側に委譲) |
+| [`/harness-audit`](./harness-audit.md) | `.claude/` ハーネスを 7 カテゴリで採点し改善優先度を提示 | 設定の点検 / 新しい skill / agent / hook を入れた後 |
+
+## 使い分け
+
+- **`/migrate-new` vs [`create-migration` skill](../skills/create-migration/SKILL.md)**:
+  - 雛形だけ素早く欲しい → `/migrate-new`
+  - エンティティ差分から自動生成、または CONCURRENTLY などの注意点を含めて完全に誘導してほしい → `create-migration` skill (`migration:generate`)
+- **`/changelog-add` vs 手動編集**:
+  - サブセクションの placeholder `-` 置換や、過去リリースセクションへの誤編集を避けるため、原則コマンドを使う。
+- **`/quality-gate` のスコープ**:
+  - 編集途中の軽量チェック (lint + unit test) は `/quality-gate` で十分。重い e2e / federation / Cypress は CI 側で実行されるため、ローカルでは原則回さない。
+
+## 新規追加時の方針
+
+- 既存の `superpowers` / `pr-review-toolkit` などのプラグイン提供スラッシュコマンドで足りる場合は新規追加しない。
+- frontmatter には最低限 `description` を指定し、引数を取るなら `argument-hint`、可能なら `allowed-tools` も指定する (permission prompt を最小化するため)。
+- 長時間ビルド (2 分超) を伴うコマンドはインライン `` !`<cmd>` `` を使わず、本文で `Bash` ツール呼び出し時の `timeout` を指示する。
--- a/.claude/commands/changelog-add.md
+++ b/.claude/commands/changelog-add.md
@@ -0,0 +1,49 @@
+---
+description: CHANGELOG.md の Unreleased セクションに 1 行追記する
+argument-hint: <general|client|server> <Prefix>: <description>
+allowed-tools: Bash(awk:*), Bash(git diff:*), Read, Edit
+---
+
+## 引数
+
+引数: `$ARGUMENTS`
+
+## 現在の Unreleased セクション
+
+!`awk '/^## Unreleased/,/^## [0-9]/' CHANGELOG.md`
+
+## タスク
+
+1. **引数の解析**
+   `$ARGUMENTS` を以下の形式として解釈する:
+   - 第 1 トークン: scope = `general` / `client` / `server` のいずれか (case-insensitive)
+   - 残り: エントリ本文。`Enhance:` / `Fix:` / `Feat:` のいずれかで始まる前提
+   - 不正な scope や、Prefix が見当たらない場合はエラー終了し、ユーザーに `argument-hint` の書式を提示する
+
+   scope は次のように見出しに変換する: `general` → `### General` / `client` → `### Client` / `server` → `### Server`。
+
+2. **対象サブセクションの状態判定**
+   上の context (現在の Unreleased セクション) を見て、対象サブセクションが以下のどちらかを判定する:
+   - **空 (placeholder のみ)**: 見出し直下に `-` 単独行のみがある状態
+   - **既存エントリあり**: `- Enhance: ...` / `- Fix: ...` / `- Feat: ...` の行が 1 つ以上ある状態
+
+3. **CHANGELOG.md の編集**
+   `Read` で CHANGELOG.md 全体を確認した後、`Edit` ツールで以下のように更新する:
+
+   - **空の場合**: 該当サブセクションの placeholder `-` 行を `- <整形済みエントリ>` で置換する。例: `### General\n-\n` → `### General\n- Enhance: 新しい機能\n`
+   - **既存ありの場合**: 既存エントリ群の **末尾** (次の空行直前) に新エントリを **append** する。順序入れ替えはしない。
+
+   `Edit` の `old_string` には、置換対象のサブセクション付近のユニークな文脈 (見出し + 直後の数行) を含め、誤マッチを防ぐ。
+
+4. **不可侵の徹底**
+   - `## Unreleased` 以下の対象サブセクションのみ編集する。
+   - `## 2026.x.x` 以下の過去リリースセクションは絶対に変更しない ([AGENTS.md §CHANGELOG](../../AGENTS.md#changelog) 参照)。
+
+5. **結果確認**
+   `git diff CHANGELOG.md` を実行し、想定通り 1 行のみ追加されていることを表示して、ユーザーに確認させる。
+
+## 例
+
+- `/changelog-add server Fix: 通知が遅延する問題を修正` → `### Server` 末尾に追記
+- `/changelog-add client Enhance: ノートの表示を改善` → `### Client` 末尾に追記
+- `/changelog-add general Feat: 新機能の追加` → `### General` 末尾に追記 (placeholder 置換)
--- a/.claude/commands/check-misskey-js.md
+++ b/.claude/commands/check-misskey-js.md
@@ -0,0 +1,42 @@
+---
+description: backend の API 変更後に misskey-js を再生成し、生成物の差分を報告する
+allowed-tools: Bash(pnpm build-misskey-js-with-types:*), Bash(git status:*), Bash(git diff:*), Bash(git branch:*)
+---
+
+## 概要
+
+backend の API endpoint やスキーマを変更した後、`packages/misskey-js/src/autogen/` の自動生成型を最新化するためのコマンド。内部で `pnpm build-misskey-js-with-types` (backend build → `api.json` 生成 → misskey-js 型生成 → ビルド → API extractor) を一括実行する。
+
+## 現在の状態 (再生成前)
+
+- 現ブランチ: !`git branch --show-current`
+- 既存の misskey-js 関連変更: !`git status --short -- packages/misskey-js/`
+
+## タスク
+
+以下の手順を順番に実行してください。
+
+1. **再生成の実行**
+   `Bash` ツールで以下のコマンドを `timeout: 600000` (10 分) を指定して実行する。内部で backend ビルドと型再生成を行うため、デフォルトの 2 分タイムアウトでは不足する。
+
+   ```bash
+   pnpm build-misskey-js-with-types
+   ```
+
+2. **差分の確認**
+   完了後、以下を実行して `packages/misskey-js/src/autogen/` の差分を確認する (`built/` は `.gitignore` 対象なので追跡対象外):
+
+   ```bash
+   git status --short -- packages/misskey-js/
+   git diff --stat -- packages/misskey-js/src/autogen/
+   ```
+
+3. **結果報告**
+   - **差分なし** → 「backend の変更は misskey-js の公開型に影響していません」と報告する。追加コミットは不要。
+   - **差分あり** → 変更ファイル一覧をユーザーに示し、`git add packages/misskey-js/src/autogen/` で再生成物もコミット対象に含めるよう案内する。`api.json` の差分が大きい場合は、API endpoint 側の `meta` / `paramDef` / `res` 定義を確認するよう促す。
+
+## 注意
+
+- このコマンドは **backend 編集後の確認** が目的。backend を変更していないのに走らせると、ビルドキャッシュ次第で no-op になる。
+- 実行中は `packages/backend/built/` や `packages/misskey-js/built/` などの中間生成物が更新されるが、これらは `.gitignore` 対象。
+- 生成物以外 (`packages/misskey-js/src/` のうち `autogen/` 以外) に予期せぬ差分が出た場合は、ローカルの編集が混入している可能性があるため、一旦中止して原因を調査する。
--- a/.claude/commands/harness-audit.md
+++ b/.claude/commands/harness-audit.md
@@ -0,0 +1,146 @@
+---
+description: Misskey の .claude/ ハーネス (skills/agents/commands) を 7 カテゴリで採点する確定的な監査。
+argument-hint: "[repo|skills|commands|agents]"
+---
+
+<!--
+SPDX-License-Identifier: MIT
+SPDX-FileCopyrightText: 2026 Affaan Mustafa and everything-claude-code contributors
+
+出典 (upstream): https://github.com/affaan-m/everything-claude-code (v2.0.0-rc.1)
+upstream path: commands/harness-audit.md
+upstream license: MIT — https://github.com/affaan-m/everything-claude-code/blob/main/LICENSE
+project-level notice: see .claude/THIRD_PARTY_LICENSES.md (Misskey 内サードパーティ一覧 + MIT 全文)
+
+Imported into Misskey .claude/ on 2026-05-10. The 7-category rubric and output contract are derived from the upstream ECC version (MIT). The runtime layer was substantially reimplemented for Misskey: the upstream relies on scripts/harness-audit.js to mechanically score, while this version asks Claude to score directly with pnpm/git/grep, and adds Misskey-specific evaluation axes (SPDX coverage / endpoint-list 登録漏れ / migration 順序 / ja-JP.yml 整合).
+
+note: 元 ECC 版は scripts/harness-audit.js (専用 Node スクリプト) で機械採点していたが、Misskey は ECC plugin runtime に依存しない方針なので、Claude が直接ファイルを読んで採点する手動運用版に書き換えた。Misskey 固有の重要観点 (SPDX 適用率 / endpoint-list 登録漏れ / migration 順序 / ja-JP.yml 整合) を評価軸として明示的に組み込んでいる。
+-->
+
+# /harness-audit — Misskey ハーネス監査
+
+Misskey リポジトリの `.claude/` 構成を 7 カテゴリで採点し、改善優先度を提示する。
+
+## Usage
+
+`/harness-audit [scope]`
+
+- `scope` (任意): `repo` (default) / `skills` / `commands` / `agents`
+
+## 評価カテゴリ (各 0-10)
+
+| # | カテゴリ | 評価軸 |
+| --- | --- | --- |
+| 1 | Tool Coverage | skill / agent / command の数、欠けているワークフロー段、重複なし |
+| 2 | Context Efficiency | frontmatter description の冗長度、SKILL.md の長さ分布、重複情報、CLAUDE.md の肥大化 |
+| 3 | Quality Gates | Stop / PreToolUse / PostToolUse hook の整備、`/quality-gate` 等の完了前ゲートの有無、自動 lint/typecheck |
+| 4 | Memory Persistence | docs/* の同期状態を評価。プロジェクト側 `.claude/memory/` は未採用方針 (auto-memory はユーザーホーム側で自動運用) のため、ここを採点起点にせず既定 5/10 から開始する |
+| 5 | Eval Coverage | testing.md の網羅、Misskey 固有の e2e/fed/Storybook/Cypress 適用ガイド |
+| 6 | Security Guardrails | SPDX 規約適用、migration 不変性ルール、ja-JP.yml 限定編集ルール、secrets 検出 |
+| 7 | Cost Efficiency | enabledPlugins の重複・過剰、context-budget の整備、MCP 過剰登録なし |
+
+## Misskey 固有の確認項目 (採点根拠コマンド)
+
+採点時に以下を実コマンドで確認する。各項目の **属するカテゴリ** は項目内に明記する (#1-#3 は Security Guardrails、#4 は Tool Coverage、#5 は Quality Gates):
+
+```bash
+# 1. [Security Guardrails] SPDX 適用率 (新規ファイル想定の汎用チェック)
+#    - node_modules を prune で除外
+#    - packages/misskey-js は MIT サブパッケージなので AGPL ヘッダーを持たない (AGENTS.md §1) → 除外
+#    - built/ なども除外
+#    候補にはなお *.config.{ts,js} / *eslint* / *.d.ts のような CI 上 SPDX 対象外
+#    (.github/workflows/check-spdx-license-id.yml の exclude 参照) も混ざるため、
+#    上位に出たファイルが「新規追加した実コード」かどうかは目視判定する。
+find packages \
+  \( -type d \( -name node_modules -o -name built -o -name dist -o -path 'packages/misskey-js' \) -prune \) \
+  -o -type f \( -name '*.ts' -o -name '*.js' -o -name '*.vue' -o -name '*.scss' \) -print \
+  | xargs -r grep -L 'SPDX-License-Identifier: AGPL-3.0-only' | head -20
+# → 上位に新規実コードが無ければ満点
+
+# 2. [Security Guardrails] ja-JP.yml 以外の locales が直近で手動編集されていないか
+#    --pretty=format: でコミットヘッダ行を抑止し、ファイル名行のみを残してから grep する。
+#    Crowdin の自動同期 commit でも他言語 yml は更新されるため、出力が 0 行になることは少ない。
+#    出力があった場合は、author / commit message を確認し Crowdin 由来か手動編集かを判定する:
+#    git log --since='30 days ago' --pretty=format:'%h %an %s' -- locales/<file>.yml
+git log --since='30 days ago' --pretty=format: --name-only -- 'locales/*.yml' \
+  | grep -v '^$' | grep -v 'ja-JP.yml' | sort -u
+# → 出力が無い、または全て Crowdin 由来 commit なら満点
+
+# 3. [Security Guardrails] migration の pending DDL 検査 (TypeORM schema builder)
+pnpm --filter backend check-migrations
+# → 0 errors (= "All migrations are clean.") なら満点
+
+# 4. [Tool Coverage] endpoint-list.ts 登録漏れ (新規 endpoint がリストにない場合)
+#    endpoints/ は再帰構造 (notes/create.ts, admin/announcements/create.ts 等) で 400+ ファイルあるため、
+#    endpoint-list.ts も `export * as '<category>/<name>' from './endpoints/<category>/<name>.js';` 形式で
+#    1 ファイル 1 行登録される。両者の行数を「再帰 .ts 数」と「export * as 行数」で比較する。
+#    e2e / 単体テストは endpoint ではないので *.test.ts を除外する。
+endpoint_files=$(find packages/backend/src/server/api/endpoints -type f -name '*.ts' ! -name '*.test.ts' | wc -l)
+list_entries=$(grep -cE "^export \* as " packages/backend/src/server/api/endpoint-list.ts)
+echo "endpoints (recursive): $endpoint_files / endpoint-list.ts entries: $list_entries"
+# 差分が 0 なら満点。差分が出たら、登録漏れの具体特定:
+comm -23 \
+  <(find packages/backend/src/server/api/endpoints -type f -name '*.ts' ! -name '*.test.ts' \
+    | sed -E 's|.*/endpoints/||;s|\.ts$||' | sort -u) \
+  <(grep -oE "^export \* as '[^']+'" packages/backend/src/server/api/endpoint-list.ts \
+    | sed -E "s/^export \* as '([^']+)'/\1/" | sort -u)
+# 出力された行が登録漏れの endpoint。0 行なら満点。
+
+# 5. [Quality Gates] console.log の混入
+grep -rn 'console\.\(log\|debug\)' packages/backend/src packages/frontend/src 2>/dev/null \
+  | grep -v 'node_modules\|test\|.spec\.\|.test\.' | wc -l
+# → 0 が理想
+```
+
+## 出力契約
+
+以下を返す:
+
+1. `overall_score` / `max_score` (repo は 70 点満点)
+2. カテゴリごとのスコア + 具体的な根拠
+3. 失敗チェック項目と該当ファイルパス
+4. Top 3 改善アクション
+5. 次に適用を推奨する skill / 手順
+
+## サンプル出力
+
+```text
+Harness Audit (repo): 55/70
+
+Tool Coverage:        9/10   (skills 5, agents 2, commands 5 — 偏りなし)
+Context Efficiency:   8/10   (description 平均 3-5 行、肥大なし)
+Quality Gates:        5/10   (Stop hook 共有設定に未登録 / `/quality-gate` あり)
+Memory Persistence:   5/10   (プロジェクト側 memory/ 未採用方針 = 既定値)
+Eval Coverage:        7/10   (testing.md 網羅、Storybook 一部抜け)
+Security Guardrails:  10/10  (SPDX 100%, locales OK, migrations clean)
+Cost Efficiency:      8/10   (context-budget 導入済 / MCP 0)
+
+Failed Checks:
+- packages/frontend/src/.../X.vue で SPDX 欠落 (Security Guardrails)
+- console.log が backend に 3 件 (Quality Gates)
+- 共有 Stop hook なし (Quality Gates) — 各 contributor が `.claude/settings.local.json` で opt-in する方針なら減点しなくて良い
+
+Top 3 Actions:
+1) [Security Guardrails] SPDX 欠落 1 ファイルを修正:
+   packages/frontend/src/.../X.vue
+2) [Quality Gates] backend の console.log 3 件を logger に置換。
+   git grep "console\.log" packages/backend/src
+3) [Cost Efficiency] enabledPlugins から未使用のものを外す。
+   .claude/docs/plugins.md と照合。
+
+Suggested next skills to apply:
+- /quality-gate で完了前に lint + unit test を回す
+- context-budget で plugin 由来の overhead を確認
+```
+
+## 採点の信頼性
+
+- 確定的: 同じ commit / 同じ `.claude/` 構成なら同じスコア
+- ヒューリスティクス: 「description の冗長度」のような主観項目は同一基準で機械的に判定
+- スクリプト不要: `pnpm` と `git`、`grep`/`find` 等の標準ツールのみ
+
+## 参考: ECC オリジナルとの差分
+
+- ECC 版は `node scripts/harness-audit.js` を直叩きする運用で、ECC リポジトリ全体に閉じた採点だった。
+- Misskey 版は **Misskey の規約 (SPDX/migration/locales/endpoint-list)** を Security 採点に組み込み、`pnpm` ベースの実コマンドで根拠を取る方式に再設計。
+- 結果として ECC への依存はゼロ。
--- a/.claude/commands/migrate-new.md
+++ b/.claude/commands/migrate-new.md
@@ -0,0 +1,81 @@
+---
+description: TypeORM migration の空雛形を生成する。スキーマ差分から自動生成したい時は create-migration skill を使うこと
+argument-hint: <PascalCaseName>
+allowed-tools: Bash(pnpm:*), Bash(ls:*), Bash(test:*), Bash(head:*), Read, Edit
+---
+
+## 引数
+
+引数: `$ARGUMENTS`
+
+## タスク
+
+1. **PascalCaseName の検証**
+   `$ARGUMENTS` が `^[A-Z][A-Za-z0-9]+$` に一致するか確認する。一致しない場合はエラー終了し、`AddFooBar` / `BirthdayIndex` のような形式を案内する。
+
+2. **既存ファイルの存在確認**
+
+   ```bash
+   ls packages/backend/migration/*$ARGUMENTS.{js,ts} 2>/dev/null
+   ```
+
+   既に同名 (タイムスタンプ違い) のファイルが存在する場合、上書きせずユーザーに別名を促す。
+
+3. **TypeORM 公式 CLI で空雛形を生成 (`-o --esm` 必須)**
+   `create-migration` skill の方針に従い、`Date.now()` を手書きするのではなく TypeORM CLI を使う。`-o --esm` で **最初から JS(ESM) を生成** させ、後続の `.ts → .js` 変換や `import { MigrationInterface }` 削除といった TS 固有構文の除去を不要にする (`-o --esm` を付けないと `.ts` + CommonJS / `implements MigrationInterface` 付きで生成され、Misskey の `ormconfig.js` (`migration/*.js` のみロード) と既存 migration スタイルに合わない):
+
+   ```bash
+   pnpm --filter backend exec typeorm migration:create -o --esm migration/$ARGUMENTS
+   ```
+
+   出力: `packages/backend/migration/<UnixMs>-<PascalCaseName>.js`
+
+4. **生成ファイルパスの取得**
+   後続ステップで使うパスを変数に受ける (`<ms>` を手書きしない):
+
+   ```bash
+   dst=$(ls -t packages/backend/migration/*$ARGUMENTS.js | head -1)
+   ```
+
+   以降のステップでは `$dst` を編集対象として扱う。完成後の典型的な形は次のようになる (参考: [packages/backend/migration/1767169026317-birthday-index.js](../../packages/backend/migration/1767169026317-birthday-index.js)):
+
+   ```js
+   export class <PascalCaseName><ms> {
+       name = '<PascalCaseName><ms>'
+
+       async up(queryRunner) {
+       }
+
+       async down(queryRunner) {
+       }
+   }
+   ```
+
+5. **SPDX ヘッダーの追加**
+   `Edit` ツールで、ファイル冒頭に以下を挿入する。CI の `spdx` ジョブが失敗するため必須:
+
+   ```js
+   /*
+    * SPDX-FileCopyrightText: syuilo and misskey-project
+    * SPDX-License-Identifier: AGPL-3.0-only
+    */
+   ```
+
+6. **migration の pending DDL 検査**
+
+   ```bash
+   pnpm --filter backend check-migrations
+   ```
+
+   TypeORM schema builder で pending DDL を検出する検査 ([scripts/check_migrations_clean.js](../../packages/backend/scripts/check_migrations_clean.js))。空雛形を作っただけの段階ではエンティティ差分との不整合が残る場合があるため、`up`/`down` を埋めた後にも再実行して 0 件になるか確認する。
+
+7. **結果報告**
+   - 生成ファイルパスを示す。
+   - `up()` / `down()` の中身が空であることを伝え、SQL を書く必要があると案内する。
+   - `down()` を空のまま放置すると本番ロールバック時に詰むため、必ず `up` の完全な巻き戻しを実装するよう促す。
+   - 詳細な手順 (`migration:generate` を使うべきケース、CONCURRENTLY などの注意点) は `create-migration` skill を参照するよう案内する。
+
+## 注意
+
+- このコマンドは **空雛形を素早く出して手書きする** 用途。エンティティ (`packages/backend/src/models/*.ts`) を変更した差分から SQL を自動生成したい場合は、このコマンドではなく `create-migration` skill 経由で `migration:generate` を使うこと。
+- マージ済み migration ファイルは絶対に編集しない ([AGENTS.md §3](../../AGENTS.md#3-マージ済み-migration-を絶対に編集しない))。
--- a/.claude/commands/quality-gate.md
+++ b/.claude/commands/quality-gate.md
@@ -0,0 +1,122 @@
+---
+description: Misskey の lint / typecheck / 高速テストを順に実行して品質ゲートを通すコマンド。完了前の軽量検証用。
+argument-hint: "[repo|backend|frontend|<path/to/file.ts>]"
+---
+
+<!--
+SPDX-License-Identifier: MIT
+SPDX-FileCopyrightText: 2026 Affaan Mustafa and everything-claude-code contributors
+
+出典 (upstream): https://github.com/affaan-m/everything-claude-code (v2.0.0-rc.1)
+upstream path: commands/quality-gate.md
+upstream license: MIT — https://github.com/affaan-m/everything-claude-code/blob/main/LICENSE
+project-level notice: see .claude/THIRD_PARTY_LICENSES.md (Misskey 内サードパーティ一覧 + MIT 全文)
+
+Imported into Misskey .claude/ on 2026-05-10. Pipeline 概念 (lint → typecheck → test) は upstream ECC 版から借用 (MIT)。実コマンド層は Misskey の pnpm + tsgo + ESLint + Vitest に固定し、formatter (Prettier/Biome) フェーズは削除した。
+
+note: 元 ECC 版は言語自動判定 + format/lint/type のジェネリック版だったが、Misskey 専用に pnpm + tsgo + ESLint + Vitest の組み合わせに固定。重い test:e2e / test:fed は含まない (CI 側で実行される)。
+-->
+
+# /quality-gate — Misskey 軽量品質ゲート
+
+`/quality-gate [scope]`
+
+完了前の **軽量** 品質チェック。重い E2E / 連合テスト (test:e2e / test:fed / Cypress) は CI 側で実行されるため、本コマンドには含めない。
+
+## Scope
+
+- `repo` (default) — 全パッケージ
+- `backend` — `packages/backend` のみ
+- `frontend` — `packages/frontend` のみ
+- `path/to/file.ts` — 単一ファイルへの ESLint --fix のみ
+
+## Pipeline
+
+### Repo scope (全部)
+
+各パッケージの `lint` スクリプト実体は `pnpm typecheck && pnpm eslint` ([packages/backend/package.json](../../packages/backend/package.json), [packages/frontend/package.json](../../packages/frontend/package.json)) で、ルートの `pnpm lint` は `pnpm --no-bail -r lint` (= 全パッケージで lint を `--no-bail` で実行)。**typecheck は lint に含まれている**ため、通常はこの 2 コマンドで十分:
+
+```bash
+# 1. Lint (= typecheck + ESLint、全パッケージ。--no-bail で最初の失敗で止まらず全結果を集める)
+pnpm lint
+
+# 2. Unit test (高速、e2e は含まない)
+pnpm --filter backend test
+pnpm --filter frontend test
+```
+
+#### 詳細を分けて見たい時のみ (optional)
+
+lint がまとめて失敗していて typecheck の結果だけ単独で見たい場合は、以下を個別に回す。**通常は不要** (lint の出力を読めば足りる):
+
+```bash
+pnpm --filter backend typecheck    # tsgo 単体
+pnpm --filter frontend typecheck   # vue-tsc 単体 (Vue SFC の型を見るため)
+```
+
+### Backend scope
+
+`pnpm --filter backend lint` は内部で `pnpm typecheck && pnpm eslint` を実行する ([packages/backend/package.json](../../packages/backend/package.json)) ので、`lint` を回せば typecheck も終わる。軽量ゲートでは typecheck の二重実行を避けるため `lint` + `test` のみ:
+
+```bash
+pnpm --filter backend lint
+pnpm --filter backend test
+```
+
+`tsgo` の出力を単独で見たい時のみ optional で `pnpm --filter backend typecheck` を別途回す。
+
+### Frontend scope
+
+`pnpm --filter frontend lint` も内部で `pnpm typecheck && pnpm eslint` を実行する ([packages/frontend/package.json](../../packages/frontend/package.json)) ため、軽量ゲートでは Backend 同様に `lint` + `test` のみ:
+
+```bash
+pnpm --filter frontend lint
+pnpm --filter frontend test
+```
+
+`vue-tsc` の出力を単独で見たい時のみ optional で `pnpm --filter frontend typecheck` を別途回す。
+
+### Single file scope
+
+```bash
+pnpm exec eslint --fix <path>
+```
+
+## Output
+
+実行したフェーズの pass/fail と件数を集計する。標準パイプラインは `pnpm lint` (typecheck 内包) と unit test のみなので、デフォルトの出力は以下のようになる:
+
+```text
+Quality Gate (repo):
+
+Lint:        PASS  (0 errors, 2 warnings)
+Backend ut:  PASS  (412/412)
+Frontend ut: PASS  (87/87)
+
+→ 完了前の軽量チェック OK。重い e2e / 連合テストは CI 側で実行される。
+```
+
+`#### 詳細を分けて見たい時のみ (optional)` で個別 typecheck (`pnpm --filter backend typecheck` / `pnpm --filter frontend typecheck`) も回した場合のみ、その結果を追加行として表示する:
+
+```text
+Quality Gate (repo):
+
+Lint:        PASS  (0 errors, 2 warnings)
+Backend tc:  PASS  (0 errors)        # optional 実行時のみ
+Frontend tc: PASS  (0 errors)        # optional 実行時のみ
+Backend ut:  PASS  (412/412)
+Frontend ut: PASS  (87/87)
+```
+
+失敗時は最初に落ちたフェーズで停止して詳細を見せる。
+
+## 関連 skill / コマンド
+
+- `/check-misskey-js` コマンド — API 変更時の misskey-js 再生成
+- [AGENTS.md §必須コマンド](../../AGENTS.md#必須コマンド) — pnpm コマンド一覧の正典
+
+## 元 ECC 版との差分
+
+- ジェネリックな言語自動判定を排除し、Misskey 固定 pipeline に。
+- formatter フェーズなし (Misskey は ESLint --fix のみ採用)。
+- e2e / federation / Cypress は重いため除外し CI 側に委譲。