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

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-18 23:35:27 +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/docs/README.md
+++ b/.claude/docs/README.md
@@ -0,0 +1,18 @@
+# Misskey – Claude Code 補助ドキュメント
+
+ルート `CLAUDE.md` には書かれていないが、開発時に参照すると便利な情報を分野別にまとめている。**Claude は必要になったタイミングで該当ファイルを Read すれば良い** (auto-load しない)。
+
+## 索引
+
+| ファイル | いつ読むか |
+|---|---|
+| [architecture.md](./architecture.md) | パッケージ構成・ビルド構造を把握したい時 / 新パッケージを跨ぐ変更を計画する時 |
+| [backend.md](./backend.md) | `packages/backend` を編集する時 (NestJS / TypeORM / API endpoint / migration) |
+| [frontend.md](./frontend.md) | `packages/frontend` を編集する時 (Vue 3 / Mk* / i18n / SCSS Modules / `os.ts`) |
+| [testing.md](./testing.md) | テストを書く・走らせる時 (Vitest 構成、Cypress、Storybook) |
+| [plugins.md](./plugins.md) | 有効化済の Claude Code プラグインの用途を確認したい時 |
+
+## 補足: ルール vs ドキュメント
+
+- 事故直結ルール (SPDX / locales / migration) と必須コマンド・CHANGELOG 書式は、リポジトリルートの [AGENTS.md](../../AGENTS.md) に集約されている。Claude Code は CLAUDE.md からの `@AGENTS.md` で常時コンテキストに乗せる。Codex / Copilot も同じファイルを読む。
+- `.claude/docs/*.md` (このディレクトリ) は **オンデマンド参照**。Claude が「知っておいた方が良いが常に持つ必要はない」内容をここに置く。
--- a/.claude/docs/architecture.md
+++ b/.claude/docs/architecture.md
@@ -0,0 +1,47 @@
+# アーキテクチャ概要
+
+## モノレポ構成 (pnpm workspaces)
+
+pnpm workspace の正は [pnpm-workspace.yaml](../../pnpm-workspace.yaml) で、以下 11 パッケージと、`packages/misskey-js` 内の sub-workspace `packages/misskey-js/generator` (型生成用の内部ジェネレータ。直接編集しない) で構成される。`package.json` の `workspaces` 配列も併記しているが、実体は pnpm-workspace.yaml が読まれる:
+
+| パッケージ | 役割 |
+|---|---|
+| `packages/backend` | NestJS 11 + Fastify 5 + TypeORM 0.3 (PostgreSQL) + Redis。HTTP/WebSocket/ActivityPub サーバー本体。 |
+| `packages/frontend` | Vue 3.5 + Vite。Web クライアント本体。 |
+| `packages/frontend-embed` | 埋め込み専用ビュー (ノート単体プレビュー等)。 |
+| `packages/frontend-shared` | frontend と frontend-embed で共有するユーティリティ・コンポーネント。 |
+| `packages/frontend-builder` | フロントエンドビルド支援 (Vite plugin など)。 |
+| `packages/sw` | Service Worker。 |
+| `packages/misskey-js` | JS/TS クライアント SDK (MIT サブパッケージ)。`src/autogen/` 配下のみ backend の OpenAPI から `pnpm build-misskey-js-with-types` で自動生成され、それ以外 (`src/index.ts` / `src/api.ts` 等) は手書き保守する。autogen 配下を直接編集しないこと。 |
+| `packages/misskey-reversi` | 内蔵リバーシゲームのロジック。 |
+| `packages/misskey-bubble-game` | 内蔵バブルゲームのロジック。 |
+| `packages/i18n` | locales 読み込み/型生成のサポート。 |
+| `packages/icons-subsetter` | アイコンのサブセット化ツール。 |
+
+その他に `packages/shared` (workspaces には含まれないが共有ファイル置き場) もある。
+
+## 重要な依存関係
+
+```
+frontend ── misskey-js (auto-generated) ── backend (OpenAPI)
+                ▲
+                └── frontend-embed, sw も依存
+```
+
+- backend の API (meta / paramDef / response) を変更したら **必ず** `pnpm build-misskey-js-with-types` を実行し、misskey-js の生成物を更新する。忘れると CI の `check-misskey-js-autogen` ジョブが落ちる。
+
+## ビルドツール
+
+- **Backend**: `rolldown` (Rust 製・Rollup 互換 API のバンドラ) でバンドル。型チェックは `tsgo` (TypeScript native preview)。
+- **Frontend**: Vite。型チェックは `vue-tsc`。
+- **Lint**: ESLint 9 (Flat Config) + `@misskey-dev/eslint-plugin`。
+
+## 国際化
+
+- `locales/` 直下に 40 言語の YAML (ja-JP.yml + 他 39 言語)。
+- **`ja-JP.yml` のみ手動編集可** (Crowdin 経由で他言語へ自動配信)。
+- フロントエンドからの参照は引数なしか引数ありかで使い分ける。詳細は [frontend.md](./frontend.md#国際化-i18n)。
+
+## ライセンス
+
+リポジトリ本体は AGPL-3.0-only。**AGPL-3.0-only 管轄かつ SPDX CI 対象ディレクトリ** の新規 `.ts` / `.js` / `.cjs` / `.mjs` / `.vue` / `.scss` / `.html` ファイルには冒頭に SPDX ヘッダー必須。`packages/misskey-js` は MIT サブパッケージなので AGPL ヘッダーを一律に付けない。条件と除外の詳細は [AGENTS.md §1](../../AGENTS.md#1-spdx-ヘッダー必須) 参照。
--- a/.claude/docs/backend.md
+++ b/.claude/docs/backend.md
@@ -0,0 +1,124 @@
+# Backend (`packages/backend`) 規約
+
+NestJS 11 + Fastify 5 + TypeORM 0.3 (PostgreSQL) + Redis。
+
+## アーキテクチャ
+
+- **DI コンテナ**: NestJS の `@Injectable()` サービス + Repository (TypeORM) パターン。
+- **DI トークン**: `@/di-symbols.js` の `DI` から `@Inject(DI.xxx)` で注入。
+- **ビルド**: `rolldown -c` で `built/` にバンドル。型チェックは `tsgo`。
+
+## API エンドポイント
+
+### 配置
+
+`packages/backend/src/server/api/endpoints/<category>/<name>.ts` (一部はトップ直下)。
+
+### 三点セット (`endpoints/ping.ts` 参照)
+
+各エンドポイントファイルは以下の 3 つを export する:
+
+```ts
+export const meta = {
+    tags: ['<tag>'],
+    requireCredential: true,           // または false (必ず明示)
+    requireModerator: false,           // 必要なら true
+    kind: 'read:account',              // OAuth scope
+    res: {
+        type: 'object',
+        optional: false, nullable: false,
+        properties: { /* ... */ },
+    },
+    errors: {
+        sampleError: {
+            message: 'Sample error message.',
+            code: 'SAMPLE_ERROR',
+            id: 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx', // UUID v4 (`x`=hex, `y`=8/9/a/b)。`crypto.randomUUID()` で生成し、他エンドポイントと重複させない
+        },
+    },
+} as const;
+
+export const paramDef = {
+    type: 'object',
+    properties: { /* JSON Schema */ },
+    required: [],
+} as const;
+
+@Injectable()
+export default class extends Endpoint<typeof meta, typeof paramDef> { // eslint-disable-line import/no-default-export
+    constructor(
+        // @Inject(DI.xxx) private xxxRepository: XxxRepository,
+    ) {
+        super(meta, paramDef, async (ps, me) => {
+            // 実装。エラーは throw new ApiError(meta.errors.xxx);
+        });
+    }
+}
+```
+
+### 注意点
+
+- **公開 API エラーとしてクライアントに返したいものは `throw new ApiError(meta.errors.<key>)` を使う**。`meta.errors` に列挙して `ApiError` でラップしないと misskey-js 側の型に出ず、レスポンスも 500 になる。
+- 一方で **想定外の例外 (DB 不整合 / 下層サービスの bug 等) は握り潰さず再 throw する**。既存 endpoint も「期待される業務エラーは `ApiError` に変換し、それ以外は `throw err;` で再 throw」の二段構え (例: [`endpoints/i/pin.ts`](../../packages/backend/src/server/api/endpoints/i/pin.ts) の `catch` 節)。生 `throw` を全面禁止すると未知例外が 200 で潰れて debug 困難になる。
+- `meta.errors.<key>.id` は **UUID** 形式。新規追加時は他エンドポイントと重複しないよう確認する。
+- `requireCredential` は `true` / `false` を必ず明示する。
+- 新規エンドポイント追加後は **`pnpm build-misskey-js-with-types`** を実行する (`misskey-js` の自動生成ファイルを更新)。
+
+### ルート登録
+
+エンドポイントは **glob 自動収集されない**。新規ファイルを `endpoints/<category>/<name>.ts` に置いただけでは API ルーティングに乗らず、404 になる。`packages/backend/src/server/api/endpoint-list.ts` にアルファベット順で 1 行追加するのが必須:
+
+```ts
+export * as '<category>/<name>' from './endpoints/<category>/<name>.js';
+```
+
+`EndpointsModule.ts` がこのファイルの全エクスポートを `Object.entries()` で反復し、NestJS の provider (`provide: 'ep:<path>'`) を生成する。詳細は [.claude/skills/add-api-endpoint/SKILL.md](../skills/add-api-endpoint/SKILL.md) のステップ 4 を参照。
+
+## モデル / Repository
+
+- エンティティ: `packages/backend/src/models/<Name>.ts` (`@Entity` + `@Column`)。
+- DI 経由で注入される Repository を経由してアクセス。
+
+## Migration
+
+詳細手順 (手書き方式 = AGENTS.md §3 と整合):
+
+> エンティティ差分からの自動生成や `CREATE INDEX CONCURRENTLY` 等のオプションを使いたい場合は [.claude/skills/create-migration/SKILL.md](../skills/create-migration/SKILL.md) の TypeORM CLI 手順を使う。手書き / CLI どちらでも `check-migrations` (pending DDL 検出) さえ通せば等価。
+
+1. **タイムスタンプ取得**: `node -e "console.log(Date.now())"`
+2. **ファイル名**: `packages/backend/migration/{timestamp}-{PascalCaseName}.js` (拡張子は `.js`)
+3. **雛形**:
+
+   ```js
+   /*
+    * SPDX-FileCopyrightText: syuilo and misskey-project
+    * SPDX-License-Identifier: AGPL-3.0-only
+    */
+
+   export class PascalCaseName1234567890123 {
+       name = 'PascalCaseName1234567890123'
+
+       async up(queryRunner) {
+           // 前進マイグレーション
+       }
+
+       async down(queryRunner) {
+           // up を完全に巻き戻す
+       }
+   }
+   ```
+
+4. **検証**:
+   - `pnpm --filter backend check-migrations` (TypeORM schema builder で pending DDL を検出する。エンティティと migration の不一致が残っているとここで非ゼロ終了する。実体は [scripts/check_migrations_clean.js](../../packages/backend/scripts/check_migrations_clean.js))
+   - `pnpm migrate` (ローカル DB に適用)
+   - `pnpm revert` (ロールバック確認)
+5. **エンティティとの整合性**: 関連する `src/models/*.ts` の `@Column` / `@Entity` も同時に更新する。
+
+> マージ済み migration の編集は **絶対禁止** ([AGENTS.md §3](../../AGENTS.md#3-マージ済み-migration-を絶対に編集しない))。
+
+## テスト
+
+- Unit: `pnpm --filter backend test` (`vitest.config.unit.ts`)
+- E2E: `pnpm --filter backend test:e2e` (`vitest.config.e2e.ts`)
+- Federation: `pnpm --filter backend test:fed` (`vitest.config.fed.ts`)
+- 配置: `packages/backend/test/` 配下。
--- a/.claude/docs/frontend.md
+++ b/.claude/docs/frontend.md
@@ -0,0 +1,76 @@
+# Frontend (`packages/frontend`) 規約
+
+Vue 3.5 + Vite + Storybook + Cypress E2E。
+
+## コンポーネント命名
+
+- 共有 / 再利用コンポーネントは **`Mk` プレフィックス** (例: `MkButton.vue`, `MkInput.vue`, `MkAbuseReport.vue`)。
+- ページ単位のものは `packages/frontend/src/pages/` 配下に置く。
+
+## SFC スタイル
+
+Composition API + `<script setup lang="ts">` を基本とする (Options API は新規導入しない)。型宣言や module スコープのユーティリティを置きたい時は、setup ブロックと**併用**する形で追加の `<script lang="ts">` ブロックを置いて構わない (例: [`MkInput.vue`](../../packages/frontend/src/components/MkInput.vue) は `SupportedTypes` 型を別ブロックで宣言してから setup を書いている)。SCSS は **CSS Modules** で書き、`<style lang="scss" module>` を使う:
+
+```vue
+<!--
+SPDX-FileCopyrightText: syuilo and misskey-project
+SPDX-License-Identifier: AGPL-3.0-only
+-->
+
+<template>
+  <div :class="$style.root">
+    <!-- ... -->
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+// ...
+</script>
+
+<style lang="scss" module>
+.root {
+  /* ... */
+}
+</style>
+```
+
+## 国際化 (i18n)
+
+- 文字列リテラルを直書きしない。
+- 引数なし: `i18n.ts.<path>` で参照する (例: `i18n.ts.deleted`)。
+- 引数あり: `i18n.tsx.<path>(...)` で関数呼び出しする (例: `i18n.tsx.takeOverConfirm({ name })`)。
+- 新規キーは **`locales/ja-JP.yml` のみ** に追加する (他言語は Crowdin で自動配信)。
+- `i18n` は `packages/frontend/src/i18n.ts` (または共有モジュール) から import する。
+
+## モーダル / 通知
+
+- `os.ts` (`packages/frontend/src/os.ts`) 経由で呼ぶ。
+- `os.alert(...)` / `os.confirm(...)` / `os.popup(...)` / `os.success(...)` など。
+- ブラウザ標準の `window.alert()` / `window.confirm()` を **直接呼ばない**。
+
+## アクセシビリティ (PR レビューで指摘されやすい点)
+
+- クリックハンドラを付けるなら `<button>` を使うか、`role="button"` + `tabindex` を付ける。
+- フォーム要素には `<label>` または `aria-label` を付ける。
+- キーボード操作可能であること。
+
+## Storybook
+
+新規共有コンポーネントには `<ComponentName>.stories.impl.ts` を併設するのが慣習 (`MkButton.stories.impl.ts` 等の例多数)。
+
+```bash
+pnpm --filter frontend storybook-dev    # localhost:6006
+```
+
+## ビルド・開発
+
+- 開発: `pnpm dev` (ルート) で backend + frontend が watch で立ち上がる。
+- ビルド: `pnpm --filter frontend build`
+- 型チェック: `pnpm --filter frontend typecheck` (vue-tsc)
+- ESLint: `pnpm --filter frontend eslint`
+
+## テスト
+
+- Unit (Vitest): `pnpm --filter frontend test`
+- Cypress E2E: `pnpm e2e` (ルートから; `start-server-and-test` で起動)
--- a/.claude/docs/plugins.md
+++ b/.claude/docs/plugins.md
@@ -0,0 +1,28 @@
+# 有効化済 Claude Code プラグイン
+
+`.claude/settings.json` で 14 プラグインが有効化されている。それぞれの典型的な利用シーンを 1 行で示す。
+
+| プラグイン | 用途 |
+| --- | --- |
+| `frontend-design` | UI コンポーネント / ページの設計・デザイン作業 (Vue 3 編集に有効) |
+| `superpowers` | TDD・debugging・brainstorming・planning 等のメタスキル群 |
+| `context7` | OSS ドキュメントの取得 (Vue 3, NestJS, TypeORM, Vitest 等) — 訓練データの古さを補う |
+| `code-review` | コードレビュー (`/code-review`) |
+| `code-simplifier` | コード整理 (`code-simplifier:code-simplifier` サブエージェント経由) |
+| `github` | GitHub PR / Issue 操作 (gh ベースだが補助コマンドあり) |
+| `skill-creator` | 新スキルの作成・改善・評価 |
+| `feature-dev` | 機能開発ガイド (`/feature-dev:feature-dev` / 内部に `code-architect` / `code-explorer` / `code-reviewer` サブエージェント) |
+| `claude-md-management` | CLAUDE.md の作成・改善 (`/claude-md-management:revise-claude-md` / `claude-md-improver` エージェント) |
+| `typescript-lsp` | TypeScript LSP 連携 (型情報を活用) |
+| `security-guidance` | セキュリティレビュー (`/security-review`) |
+| `pr-review-toolkit` | PR レビュー一式。サブエージェント: `code-reviewer` / `code-simplifier` / `comment-analyzer` / `pr-test-analyzer` / `silent-failure-hunter` / `type-design-analyzer` |
+| `claude-code-setup` | Claude Code 自動化セットアップ提案 |
+| `playwright` | ブラウザ自動操作 (フロントエンド動作確認時に有用) |
+
+## 使い分けの指針
+
+- **API 関連の調査**: `context7` で対象ライブラリのドキュメントを取得 → 編集。
+- **PR 作成前**: `pr-review-toolkit` の各エージェント (code-reviewer / silent-failure-hunter 等) を並列で走らせる。
+- **新機能の設計**: `feature-dev` → brainstorming → 実装の流れ。
+- **UI 確認**: `playwright` で `pnpm dev` の画面を直接操作。
+- **将来追加検討**: PostgreSQL MCP — TypeORM + 342 migration の調査効率化。read-only ロールで登録し、接続先 (`misskey` DB) と権限分離に注意する。
--- a/.claude/docs/testing.md
+++ b/.claude/docs/testing.md
@@ -0,0 +1,69 @@
+# テスト構成
+
+## Backend 全般の前提: `.config/test.yml`
+
+backend のテストスクリプト (`test` / `test:e2e` / `test:fed`) はすべて内部で `cross-env NODE_ENV=test pnpm compile-config` を実行し、`.config/test.yml` を読み込む ([packages/backend/package.json](../../packages/backend/package.json), [packages/backend/scripts/compile_config.js](../../packages/backend/scripts/compile_config.js))。**未作成だとテスト自体が起動しない。**
+
+未作成なら以下を 1 回だけ手動コピーする (どちらでも可):
+
+```bash
+ncp .github/misskey/test.yml .config/test.yml
+# または
+cp .github/misskey/test.yml .config/test.yml
+```
+
+補足:
+
+- ルートの `pnpm start:test` (Cypress 用にテストサーバーを起動するコマンド) を使う経路では実行時に `ncp` で自動コピーされる ([package.json](../../package.json))。それ以外で backend テストを直接走らせる時は上記の手動コピーが必要。
+- すでに `.config/test.yml` があれば各テストスクリプトの内部 `compile-config` で十分なので、追加で `pnpm --filter backend compile-config` を叩く必要はない。
+- `pnpm start:test` は backend e2e テスト (`pnpm --filter backend test:e2e`) の前提ではない (ポート競合の元になるため使わないこと)。
+
+## Backend (Vitest 4, 3 設定)
+
+| 種別 | 設定ファイル | 実行コマンド |
+| --- | --- | --- |
+| Unit | `packages/backend/vitest.config.unit.ts` | `pnpm --filter backend test` |
+| E2E (HTTP / DB) | `packages/backend/vitest.config.e2e.ts` | `pnpm --filter backend test:e2e` |
+| Federation | `packages/backend/vitest.config.fed.ts` | `pnpm --filter backend test:fed` |
+
+- 配置: `packages/backend/test/`
+- 事前準備は [§Backend 全般の前提: `.config/test.yml`](#backend-全般の前提-configtestyml) を参照。
+- カバレッジ: `pnpm --filter backend test-and-coverage`
+
+## Frontend (Vitest)
+
+```bash
+pnpm --filter frontend test                # 1 回実行
+pnpm --filter frontend test-and-coverage   # カバレッジ付き
+```
+
+- 主な配置: `packages/frontend/test/*.test.ts` (例: `i18n.test.ts`, `theme.test.ts`, `is-birthday.test.ts`)。
+- ビルドツール周りなど対象コードと隣接させた方が分かりやすいテストは、コードと同じディレクトリに `*.test.ts` として置く (例: [`packages/frontend/lib/rollup-plugin-unwind-css-module-class-name.test.ts`](../../packages/frontend/lib/rollup-plugin-unwind-css-module-class-name.test.ts))。
+- 共有コンポーネント (`MkX.vue`) のユニットテストは現状少なく、`*.spec.ts` / `__tests__/` 形式は採用していない (Storybook + Cypress でカバー)。
+
+## E2E (Cypress)
+
+ルートから実行する:
+
+```bash
+pnpm e2e                # start:test サーバーを立てて Cypress run
+pnpm cy:open            # 対話的に開く
+```
+
+- 設定: ルート `cypress.config.ts`。テスト本体は `cypress/` 配下。
+
+## Storybook (frontend)
+
+```bash
+pnpm --filter frontend storybook-dev      # http://localhost:6006
+pnpm --filter frontend build-storybook    # 静的ビルド
+```
+
+- 各コンポーネント横に `*.stories.impl.ts` を併設する慣習 (例: `MkButton.stories.impl.ts`)。
+- Chromatic (`pnpm --filter frontend chromatic`) で視覚回帰チェック。
+
+## ローカル DB / Redis (テスト・開発共通)
+
+```bash
+docker compose -f compose.local-db.yml up -d
+```