<a id="repository-guide"></a>

# リポジトリガイド

<!-- i18n: source=docs/development/repository-guide.md blob=680d8d038e278f6e630e4556f475452ba591d298 model=claude-sonnet-5-5 -->
> このページは[英語の原文](https://github.com/ClickHouse/loom/blob/main/docs/development/repository-guide.md)の機械翻訳です。内容は英語の原文が優先されます。
> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/development/repository-guide.md), which is authoritative.


トップレベルの各ディレクトリに何が置かれているか、`server/` 内のどこに各関心事があるか、コードを読む順序、そしてこれを守らないとプルリクエストが通らない規約を説明します。

<a id="top-level-layout"></a>

## トップレベルの構成

| パス                                                                                                                                                         | 内容                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `server/`                                                                                                                                                    | FastAPI サーバー：ドメインパッケージ（メモリ、コード、トラッカーなど）、オペレーションレジストリ、ワーカー、トランスポート、CLI、設定                                                                                                                                                                                                                                                     |
| `extractor/`                                                                                                                                                 | リファレンス抽出サービス（`loom_extractor/`）：形式の検出とドキュメントパーサー。サーバーの外で実行する。イメージ（`Dockerfile`、`ghcr.io/clickhouse/loom-extractor` としてリリース）とロック（`uv.lock`）を含む。[ドキュメント抽出](https://github.com/ClickHouse/loom/blob/main/docs/architecture/document-extraction.md)を参照                                                          |
| `sdk/python/`                                                                                                                                                | Python SDK。`clickhouse-loom` として公開（`sdk/python/loom/`）                                                                                                                                                                                                                                                                                                                           |
| `sdk/typescript/`                                                                                                                                            | TypeScript SDK。`@clickhouse/loom` として公開（`sdk/typescript/src/`）                                                                                                                                                                                                                                                                                                                   |
| `frontend/`                                                                                                                                                  | `/` で配信される React ダッシュボード（Vite + Tailwind）。`src/`、`e2e/` 内の Playwright スペック、`scripts/bundle_budget.mjs`                                                                                                                                                                                                                                                           |
| `schemas/`                                                                                                                                                   | `migrations/`（番号付き SQL）、`schema.sql`（生成された現在のスキーマ）、`otel/`（ClickStack OTel テーブル）、`ops/`（手動実行用 SQL）。[`schemas/README.md`](https://github.com/ClickHouse/loom/blob/main/schemas/README.md)を参照                                                                                                                                                         |
| `dev/`                                                                                                                                                       | compose スタック、運用スクリプト（`loom_ingest.py`、`loom_init.py`、`onboard_tenant.py`、バックアップとリストア、`verify_audit_chain.py`）、`ci_start_clickhouse.sh`、`redeploy_preflight.sh`                                                                                                                                                                                              |
| `deploy/`                                                                                                                                                    | ClickHouse サーバー設定（`clickhouse-config/`）、Lemmagen3 モデル（`lemmagen3/`）、ブルー/グリーンプロキシ（`proxy/`）、Helm チャート（`helm/`）、リポジトリジョブのサンドボックス用 AppArmor プロファイル（`apparmor/`）、スタンドアロン用の env テンプレート（`standalone/`）、定期的な名前空間コピーの CronJob（`okf-sync/`）、ダッシュボード（`dashboards/`、`hyperdx_dashboards.md`、`clickstack_sources.sh`） |
| `bench/`                                                                                                                                                     | ベンチマークのハーネスとゲート、そのフィクスチャ（`fixtures/`）、データセット、ルーブリック、受け入れ評価とスキル評価。[ベンチマーク](/ja/benchmarks/overview)を参照                                                                                                                                                                                                                   |
| `integrations/`                                                                                                                                              | クライアント統合：Claude Code と Codex のプラグイン、Cline のフック、grep shim、Cursor と汎用のトランスクリプトフック、OKF CI ゲート                                                                                                                                                                                                                                                      |
| `skills/`                                                                                                                                                    | スタンドアロンの Agent Skills：`loom-code` と `loom`（サーバーイメージに同梱され `mentor.guide` が返すエージェント向けガイド）                                                                                                                                                                                                                                                           |
| `scripts/`                                                                                                                                                   | `codegen/`（ジェネレーター）、`gates/`（CI のラチェットとガード）、`ops/`（運用ツール）、`scip_harness/`（コンパイラティアのプロデューサー）、`docs_site/`（ドキュメントサイトのフック、テーマのオーバーライド、固定されたビルダー、IndexNow への送信）、`i18n/`（翻訳ジェネレーターとその鮮度チェック）                                                                                   |
| `tests/`                                                                                                                                                     | `unit/`、`integration/`、`analyzer/`、`code_lanes/`、`fixtures/`（後述）                                                                                                                                                                                                                                                                                                                 |
| `examples/`                                                                                                                                                  | 実行可能な統合例（`claude_agent_loop.py`、`ledger_run.py`、`log_conversation.py`、`onboarding_walkthrough.py`）と、教師が自分のリポジトリにコピーするコースのスターター（`course-starter/`、[教育](/ja/guides/teaching#hand-out-the-labs-as-an-assignment)）                                                                                                                             |
| `i18n/`                                                                                                                                                      | README、クイックスタート、ユースケースページの機械翻訳。`LANGUAGES` の言語ごとに 1 フォルダー。`scripts/i18n/translate.py`（`.github/workflows/i18n.yml`）で生成され、手動では編集しない                                                                                                                                                                                                   |
| `docs/`                                                                                                                                                      | このドキュメント。`mkdocs.yml` と `scripts/docs_site/` がドキュメントサイトとしてビルドする（`.github/workflows/docs-site.yml`）                                                                                                                                                                                                                                                         |
| `.github/`                                                                                                                                                   | CI、リリース、スキャンのワークフロー（`workflows/`）、issue とプルリクエストのテンプレート、`social-preview.png`（Settings → General → Social preview でアップロードする画像。GitHub はアップロードされたコピーのみを読む）                                                                                                                                                              |
| `.devcontainer/`                                                                                                                                             | GitHub Codespaces のお試し環境：インストーラーで最新リリースをインストールし Claude Code を接続する dev container。開発環境ではない（[クイックスタート](/ja/getting-started/quickstart#try-it-in-github-codespaces)）                                                                                                                                                                  |
| `Dockerfile`, `Makefile`, `redeploy.sh`, `pyproject.toml`, `uv.lock`                                                                                         | サーバーのイメージ、タスクランナー、ブルー/グリーンのデプロイスクリプト、サーバーパッケージとそのロックファイル                                                                                                                                                                                                                                                                          |
| `server.json`, `context7.json`, `CITATION.cff`, `gemini-extension.json`, `.claude-plugin/`, `.cursor-plugin/`, `plugin.json`, `mcp.json`, `.agents/plugins/` | MCP Registry のリスト、ドキュメントインデックスの設定、GitHub が「Cite this repository」として表示する引用情報、Gemini CLI 拡張のマニフェスト、`loom-code` スキルのマニフェストを含む Claude Code マーケットプレイス、Cursor のマーケットプレイスとプラグイン、GitHub Copilot CLI がインストールする Agent Plugins パッケージ、Codex マーケットプレイス                                    |
| `llms-install.md`                                                                                                                                            | コーディングエージェントが Loom をインストールし MCP サーバーとして追加する手順                                                                                                                                                                                                                                                                                                          |
| `AGENTS.md`, `CLAUDE.md`                                                                                                                                     | すべてのコーディングエージェントが読む指示。`CLAUDE.md` は `AGENTS.md` をインポートする                                                                                                                                                                                                                                                                                                  |
| `.claude/`, `.agents/skills/`                                                                                                                                | エージェントのスキル、パス単位のルール、読み取り専用のレビュアーサブエージェントとそのフック、プロジェクトの権限設定。`.agents/skills/` は各スキルを Codex 向けにリンクする                                                                                                                                                                                                               |

<a id="inside-server"></a>

## server/ の内部

`server/` はドメインごとに構成されています。リクエストはトランスポートから入り、オペレーションレジストリによってドメインの `app/` にあるハンドラへディスパッチされます。ハンドラは `domain/` の純粋なロジックを実行し、そのドメインの SQL を保持する `store/` のリポジトリを通じて読み書きします。[サーバーのレイアウト](/ja/architecture/server-layout)には、コントラクトテストが強制する import ルールを含む全体マップがあります。リクエストの経路は[システム概要](https://github.com/ClickHouse/loom/blob/main/docs/architecture/system-overview.md)にあります。

| パッケージ / モジュール                                                                                 | 役割                                                                                                                                                                                                                                                                                                                         |
| ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `memory/`, `code/`, `tracker/`, `knowledge/`, `erasure/`, `tasks/`, `identity/`, `insights/`            | ドメインパッケージ。それぞれ最大 5 つのレイヤーを持ちます。`api/`（ワイヤモデル `models*.py` と `Operation` リスト `ops*.py`）、`app/`（ハンドラとオーケストレーション）、`domain/`（純粋なロジック）、`store/`（ClickHouse リポジトリと行ビルダー。`memory/store/rows.py` にバージョン行ビルダーがあります）、`workers/`（バックグラウンドループ） |
| `operations/`                                                                                           | レジストリのコア。`Operation` と `Role`（`base.py`）、`registry.py`（すべてのドメインの op グループを import し、`ALL_OPERATIONS` と `OPERATIONS_BY_NAME` を構築します）、`toolsets.py`、読み取りプロジェクション、リーチ集計                                                                                                  |
| `transport/`                                                                                            | HTTP（`http.py`）と MCP（`mcp.py` および `mcp_schemas`、`mcp_config`、`mcp_tools`、`mcp_identity`）、引数フィードバック、ボディ制限                                                                                                                                                                                          |
| `workers/`                                                                                              | ワーカーレジストリ（`registry.py`、`_WORKERS`）と、それを実行するスーパーバイザー（`supervisor.py`）。各ループはそのドメインの `workers/` にあります                                                                                                                                                                         |
| `settings/`                                                                                             | すべての設定を `catalog.py` に集約。領域ごとに 1 セクションで、`Settings` に合成されます                                                                                                                                                                                                                                     |
| `auth/`                                                                                                 | JWT の発行と検証、ロールと権限付与、ログイン、OIDC、セルフサインアップ、失効                                                                                                                                                                                                                                                 |
| `embedding/`, `llm/`                                                                                    | 差し替え可能なプロバイダーのインターフェース（OpenAI、Anthropic、Gemini、local、fake）、キャッシュ、フォールバック                                                                                                                                                                                                           |
| `observability/`                                                                                        | レジャーエミッター、監査ログ、コスト集計と予算、OTel のメトリクスとスパン、`/v1/health` が報告する `problems` リスト                                                                                                                                                                                                         |
| `clients/`                                                                                              | 外部サービス向けの HTTP クライアント（共有プロバイダープール、GitHub）                                                                                                                                                                                                                                                       |
| `storage/`                                                                                              | テーブルごとの TTL の合成                                                                                                                                                                                                                                                                                                    |
| `cli/`                                                                                                  | `loom` コマンドツリー（`app.py` が組み立てます）                                                                                                                                                                                                                                                                             |
| `main.py`, `boot.py`, `health.py`, `wiring.py`                                                          | FastAPI アプリとそのライフスパン（ワーカー、トランスポート）、起動・シャットダウンの手順（起動時マイグレーション、失効スナップショット）、`/v1/health`、`wire()`                                                                                                                                                              |
| `core/ch.py`                                                                                            | ClickHouse クライアント、プーリング、クエリの帰属（`set_query_tag`）                                                                                                                                                                                                                                                         |
| `core/errors.py`                                                                                        | 型付きエラー（`LoomServerError` のサブクラス）とその HTTP ステータス                                                                                                                                                                                                                                                         |
| `core/ratelimit.py`, `core/ratelimit_shared.py`, `core/idempotency.py`, `memory/app/blacklist_guard.py` | リクエスト経路のガード                                                                                                                                                                                                                                                                                                       |
| `core/schema/`                                                                                          | マイグレーションランナー（`migrate.py`）とコンテナ間ロック（`migrate_lease.py`）、およびランナーと再構築ツールが共有するスキーマ書き換え（`table_rebuild.py`、`vector_codec_ddl.py`）                                                                                                                                         |

<a id="inside-tests"></a>

## tests/ の内容

| パス                 | 内容                                                                                                                                                           |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tests/unit/`        | ClickHouse を必要としない高速なテスト。`snapshots/`（CLI のツリーとヘルプ、ワーカーレジストリ、SDK の公開 API）、`fixtures/`、共有ヘルパーを含む                |
| `tests/integration/` | 実行中のサーバーと ClickHouse に対するテスト（`tests/conftest.py` と `tests/integration/conftest.py` が接続を設定する）。プリンシパル間のリークを調べるプローブを含む |
| `tests/analyzer/`    | ステートメントコーパス。マイグレーション済みの空のテーブルに対して、すべての SQL ビルダーの形を `EXPLAIN QUERY TREE` で確認する。詳細は [README](https://github.com/ClickHouse/loom/blob/main/tests/analyzer/README.md) を参照 |
| `tests/code_lanes/`  | SQL とシェルのレーンのコーパス。コードインデックスが `tests/fixtures/code_lanes/` から導出する内容を、コミット済みの期待値と比較する                           |
| `tests/fixtures/`    | 複数のスイートで共有する入力                                                                                                                                   |

各スイートの実行方法、スキップ条件、CI でのゲートについては、[テスト](/ja/development/testing)を参照してください。

<a id="reading-order-for-a-new-contributor"></a>

## 新しいコントリビューター向けの読む順序

1. [README](https://github.com/ClickHouse/loom/blob/main/README.md) と [システム概要](https://github.com/ClickHouse/loom/blob/main/docs/architecture/system-overview.md)：製品の外面とシステムの構成。
2. [`server/operations/registry.py`](https://github.com/ClickHouse/loom/blob/main/server/operations/registry.py)：すべてのトランスポートが走査するワイヤ op のレジストリ。
3. `server/main.py` の lifespan：マイグレーション、ワーカー、トランスポートがどのように接続されるか。
4. 変更対象に対応する `server/<domain>/api/ops*.py` の op グループ。続けて `server/<domain>/app/` にあるそのハンドラと、ハンドラが呼び出す `server/<domain>/store/` のリポジトリ。
5. 読み書きするテーブルについては [`schemas/schema.sql`](https://github.com/ClickHouse/loom/blob/main/schemas/schema.sql)。
6. [`AGENTS.md`](https://github.com/ClickHouse/loom/blob/main/AGENTS.md) と `.claude/rules/`：規約とその理由。

<a id="conventions-that-are-not-obvious"></a>

## 自明ではない規約

[CONTRIBUTING.md](https://github.com/ClickHouse/loom/blob/main/CONTRIBUTING.md#conventions-that-arent-obvious) に規約の一覧があり、その理由は [`AGENTS.md`](https://github.com/ClickHouse/loom/blob/main/AGENTS.md) と `.claude/rules/` 配下のルールに記載されています。次のテストとゲートがこれらの規約を強制します。

| ゲート                                                                           | 守られる内容                                             |
| -------------------------------------------------------------------------------- | -------------------------------------------------------- |
| 生成された SDK テーブル、到達範囲の集計（[コード生成](/ja/development/code-generation)）      | op はレジストリの行である                                |
| `tests/integration/test_cross_principal_leakage.py`                              | 組織全体 ID の op は、他者の行を `found=False` として隠す |
| `test_memory_versions_schema.py`                                                 | `loom.memory` の列が `loom.memory_versions` に反映される |
| `test_migrations_additive.py`、台帳のチェックサム（[マイグレーション](/ja/development/migrations)） | マイグレーションは追加のみで、編集しない                 |
| `test_every_table_is_classified.py`                                              | すべてのテーブルが消去に関して分類されている             |
| `test_settings_attribute_access.py`、`test_settings_reference.py`                | 設定は `settings.<field>` として読み取られ、リファレンスは最新である |
| `test_worker_registry_snapshot.py`、`test_worker_registry_parity.py`             | ワーカーはレジストリの行である                           |
| ruff `BLE001`                                                                    | 広範な except には理由を記す                             |
| `scripts/gates/function_length_gate.py`                                          | どの関数もベースラインを超えて長くならない               |
| `tests/unit/test_public_copy.py`                                                 | リポジトリのテキストは製品中立である                     |

基盤となる構造（唯一のエンジンとしての ClickHouse、アイデンティティタプル、行ごとのコンテンツハッシュ監査、5 つの信念改訂操作）については、プルリクエストに設計上の根拠を記載し、対応するアーキテクチャのページを更新する必要があります（[重要な変更](https://github.com/ClickHouse/loom/blob/main/CONTRIBUTING.md#material-changes)）。

<a id="related"></a>

## 関連ドキュメント

- [ローカル開発](https://github.com/ClickHouse/loom/blob/main/docs/development/local-development.md)、[テスト](/ja/development/testing)、[コード生成](/ja/development/code-generation)
- [オペレーションの追加](/ja/development/adding-an-operation)、[ワーカーの追加](https://github.com/ClickHouse/loom/blob/main/docs/development/adding-a-worker.md)、[テーブルの追加](/ja/development/adding-a-table)、[言語サポートの追加](/ja/development/adding-language-support)、[Loom の拡張](/ja/development/extending-loom)
