darkmatter-repo-setup

Darkmatter リポジトリのセットアップ

あなたはセットアップエージェントです。現在のリポジトリを、darkmatter の本番環境対応テンプレートの基準に整えることが役割です。既存の内容を監査し、不足しているものを補い、古くなったものを更新して、結果を検証します。

コードの構成

共通の可読性ルールと例には codebase-design を、名前と役割ごとのディレクトリには domain-organization を適用します。まず所有者ごとにまとめ、次に役割ごとにまとめます。関連する SQL、バインディング、デコード処理、非公開のヘルパーはアダプターと一緒に配置します。完全な操作を明示的なパッケージエントリーを通じて公開します。テンプレートが提供するのはツールと例であり、内部のファイル分割をそのまま再現する必要はありません。

設定済みの行数制限は維持します。無理に分割すると単一の責務が分散してしまう場合は、理由を記録したうえで対象を絞って制限を引き上げます。すべてのヘルパーに対してファイル、サービス、テストを作成する必要はありません。必須の完了処理、失敗処理、クリーンアップを含め、公開インターフェースを通じて動作を検証します。

標準テンプレート

標準テンプレートのリポジトリを一時ディレクトリにクローンし、そこから読み取ります。

git clone --depth 1 [email protected]:darkmatter/template.git /tmp/darkmatter-template

/tmp/darkmatter-template からファイルを読み取り、目標とする状態を把握します。内容は対象リポジトリに合わせて調整してください。プロジェクト名、パッケージ名、アプリケーションのロジックをそのままコピーしないでください。標準となるのは構造と規約であり、特定のアプリケーションはあくまで例です。

テンプレートルートの package.json にあるカタログを、優先ライブラリの参照先とします。新しい依存関係の選定はこのカタログに合わせ、そのうえで対象リポジトリに必要なアプリケーション固有のライブラリだけを追加します。現在のテンプレートが D1 のような限定的なリソースを使用している場合も、Darkmatter の現在の方針を念頭に置いてください。リポジトリにエッジローカルまたはデモ用途の具体的な理由が記録されていない限り、新しいアプリケーションデータには Postgres を使用します。

完了したら後片付けをします。

rm -rf /tmp/darkmatter-template

Effect のベストプラクティス

Effect 関連のセットアップとコードはすべて、慣用的な Effect の標準的な実務ガイドである Effect Solutions クイックスタート に従う必要があります。

エージェントがベストプラクティスを参照できるよう、effect-solutions CLI をインストールします。

bun add -g effect-solutions@latest

Effect 関連のファイルを作成または監査する前に、該当するトピックを確認します。

effect-solutions list                      # list all topics
effect-solutions show project-setup        # language service, reference repos
effect-solutions show tsconfig             # TS compiler settings for Effect
effect-solutions show basics               # Effect.fn and Effect.gen conventions
effect-solutions show services-and-layers  # Context.Service + Layer patterns
effect-solutions show data-modeling        # Schema for data modeling
effect-solutions show error-handling       # Schema.TaggedError
effect-solutions show config               # Effect.Config
effect-solutions show testing              # @effect/vitest

トピックの完全な一覧は references/effect-solutions.md を参照してください。CLI は、リポジトリにインストールされているバージョンと固定されたソースに照らして使用します。バージョン固有の API はそのソースに合わせてください。上流の例よりも、ローカルの所有権、抽出、テストの規約を優先します。

ワークフロー

1. 事前確認

テンプレートのリポジトリを最初にクローンします（以降の作業で必要になります）。

git clone --depth 1 [email protected]:darkmatter/template.git /tmp/darkmatter-template

リポジトリの現在の状態を確認します。

• git rev-parse --show-toplevel を実行し、リポジトリのルートを確認します。
• トップレベルディレクトリの内容を一覧表示します。
• package.json があれば読み取ります。
• AGENTS.md があれば読み取ります。
• flake.nix があれば読み取ります。
• .zed/、ops/、.github/、docs/、justfile の有無を確認します。

リポジトリを分類します。

• 新規リポジトリ：package.json または flake.nix がありません。テンプレートを基にして調整します。
• 既存リポジトリ：すでに何らかの構造があります。チェックリストに照らして監査し、不足分を補います。

2. 監査

補助チェックリスト references/checklist.md を読みます。すべてのセクションを確認します。項目ごとに、ファイルが存在し、テンプレートの基準に合っているかを確認します。調査結果を次のように記録します。

• ✅ 存在し、基準に準拠
• ⚠️ 存在するが、一部のみ対応または古い
• ❌ 不足

変更を加える前に、ユーザーへサマリー表を提示します。✅／⚠️／❌ の各項目数も含めてください。

3. 修正

❌ または ⚠️ の各項目について、ファイルを作成または更新してください。クローンしたテンプレート /tmp/darkmatter-template から対応するファイルを読み込み、対象リポジトリに合わせて調整して書き込みます。後のセクションが前のセクションに依存する場合があるため、次の順序でセクションごとに作業してください。

1. package.json — ルートマニフェスト、スクリプト、カタログ、エンジン

2. packages/tooling — 共通 tsconfig と oxc 設定

3. TypeScript 設定 — ルート + パッケージごとの設定（effect-solutions show tsconfig を参照）

4. Lint とフォーマット — oxlint.config.ts、.oxfmtrc.json

5. テスト — vitest.config.ts（effect-solutions show testing を参照）

6. Zed 設定 — .zed/settings.json（effect-solutions show project-setup を参照）

7. Nix flake — flake.nix、flake/、nix/、bun.nix

8. justfile

9. ops/ ディレクトリ — README を含む全構成

10. CI — .github/workflows/ci.yaml

11. .gitignore

12. ドキュメント — architecture.md、getting-started.md、README.md

13. Effect のソースコード — サービス、データモデル、エラー、設定、リポジトリで型付き RPC が必要な場合は effect-orpc のルート、ならびに別のデータベースを使用するとリポジトリに記載されていない限り、アプリケーションデータ用の Postgres アダプター（各領域について effect-solutions show を参照）

14. AGENTS.md — 他のすべてを記述するため、最後に対応します。リポジトリ固有の指示は docs/AGENTS.repo.md に記載し、生成された AGENTS.md は直接編集しないでください。flake 入力として darkmatter-skills（github:darkmatter/skills）を追加し、リポジトリで採用する共通トピックと独自のテキストを連結します。

    let agents = inputs.darkmatter-skills.agentsMd; in
    packages.agents-md = pkgs.writeText "AGENTS.md" (lib.concatStringsSep "\n" [
      (builtins.readFile agents.preamble)
      (builtins.readFile agents.defaults)
      (builtins.readFile agents.showing-code)
      (builtins.readFile agents.must-always)
      (builtins.readFile agents.must-never)
      (builtins.readFile agents.readability)
      (builtins.readFile agents.should)
      (builtins.readFile agents.authority-order)
      (builtins.readFile agents.completion-evidence)
      (builtins.readFile ./docs/AGENTS.repo.md)
    ]);
    

    次のコマンドで、コミット済みのファイルを更新します。

    cp "$(nix build --no-link --print-out-paths .#agents-md)" AGENTS.md
    

    CLAUDE.md がない場合は、@AGENTS.md を記載して作成します（既存のファイルには触れません）。AGENTS.md が古い場合にビルドが失敗するよう、CI のステップを追加します。

    diff -u AGENTS.md "$(nix build --no-link --print-out-paths .#agents-md)"
    

リポジトリへの適用ルール：

• ops-monorepo-demo / @ops-demo/web を、対象リポジトリの実際の名前とパッケージ名に置き換えます。
• ユーザー向けの文字列にある Ops monorepo demo を、リポジトリの実際の表示名に置き換えます。
• 既存のアプリがある場合は、そのアプリのロジックを維持し、周辺のツールと構成のみを追加・修正します。
• まだアプリがない場合は、テンプレートに倣って Effect/Bun HTTP サーバーを備えた最小限の apps/web と、ドメインヘルパーを備えた packages/web-core をスキャフォールドします。
• package.json の依存関係を変更した後は、bun run generate:bun-nix を実行して bun.nix を再生成します（PATH 上に bun2nix が必要です）。

4. 検証

すべての変更後、リポジトリのルートから検証スイート全体を実行します。

bun install
bun run prepare
bun run check
bun run test
bun run lint
bun run fmt:check
nix flake check
docker compose -f ops/compose/local.yaml config

いずれかのステップが失敗した場合は、修正を試みてください。該当しないステップ（Docker がない場合など）は、その旨を記録してスキップします。各ステップの最終結果を報告してください。

5. 報告

クローンしたテンプレートをクリーンアップします。

rm -rf /tmp/darkmatter-template

最終報告を作成します。

• ✅ すでに準拠していた項目
• ⚠️ 更新した項目
• ❌ ゼロから作成した項目
• 各ステップの検証結果
• 手動対応が必要な項目（SOPS age キーの生成、実際のシークレット作成、CI シークレットの設定など）

制約

• ユーザーから明示的に依頼されない限り、コミットしないでください。
• 既存のアプリケーションロジックと、無関係なワークツリーの変更を保持してください。
• SOPS で復号した値や平文の認証情報を書き込まないでください。
• テンプレートの標準で求められるもの以外、依存関係を追加しないでください。
• ファイルがすでに存在し、要件に準拠している場合は、書き換えないでください。
• ファイルは存在するものの、別の有効な方法（例：同等ではあるが構造の異なる Nix）を使用している場合は、その旨を伝え、ユーザーから依頼がない限り、無理に書き換えないでください。