opencode-ts

Opencode TypeScript

opencode のコアチームのようにコードを書いてください。このスキルには、リポジトリから抽出した実際のコードが含まれています。抽象的なルールではなく、完全な実装です。タスクに応じて、以下のワークフローに従ってください。

---

実装（新しいコード）

以下のフェーズを順番に進めてください。

1. 方針を決める — どこに追加するか？

architecture.md を読み込みます。以下を確認してください。

• この動作をどのモジュールが担うか
• どの依存関係の方向が許されているか
• どのファイル命名規則に従うか
• 新しいモジュールにするか、既存モジュールに追加するか

2. 既存コードを調べる — すでにあるものは何か？

helpers-deep-dive.md を読み込みます。ユーティリティを書く前に、必ず以下を確認してください。

• util/、effect/、bus/、sync/ にすでに存在するか
• 使用状況マトリクスを確認し、他のモジュールがどのように使っているか
• 存在する場合はそれを使います。存在しない場合は、まずインラインで実装し、扱いにくさが繰り返される場合にのみ切り出します。

すばやく調べる場合は、primitives.md を参照してください（短縮版。インポートパスとシグネチャのみ）。

3. 実装する — コードを書く

実装内容に合ったリファレンスを読み込みます。

実装するもの...	読み込むリファレンス
サービスモジュール（名前空間 + Effect サービス + スキーマ + イベント）	service-module.md
ツール、またはツールの動作変更	tool-module.md
データベースのテーブル、スキーマ、イベント、エラー型	schemas-and-state.md
サーバーのルート、設定、プラグイン、プロジェクトのライフサイクル	server-and-routes.md
テスト	test-writing.md

4. チェックゲート — 続行する前に、コードはすべての項目に合格する必要があります

style-dna.md を読み込みます。以下のいずれかに不合格の場合は、レビューに進む前にコードを修正してください。

• 明確な場合は、変数名を単語1つにする
• try／catch、else、any を使わず、不要な分割代入をしない
• let と変更より、const と三項演算子を使う
• Drizzle のフィールドは snake_case にし、境界スキーマには .annotate({ identifier })、フィールドには .annotate({ description }) を付ける
• DTO、イベント、ツールのパラメーターには、Zod ではなく Effect Schema（Schema.Struct／Schema.Schema.Type）を使う
• サービスにはプレーンな async クラスではなく Effect を使う
• モジュールの末尾を export * as X from "." にする。ファイル内で export namespace X {} を使わない
• 第7節「コンパイルは通るが却下されるパターン」のパターンを差分に含めない

いずれかのチェックに不合格の場合は、先に進まないでください。 フェーズ3に戻って修正してください。

5. レビューゲート — 以下に該当する場合は差分を却下する

review-voice.md を読み込みます。差分には以下のいずれも含めてはいけません。含まれている場合は、提出前に修正してください。

• タスクの範囲外のファイルへの変更
• as any または as unknown as キャスト
• コミュニティのプリミティブや @/util/* ヘルパーと重複するカスタムユーティリティ
• models.dev に置くべきプロバイダー固有のコード
• コミットに明確な理由が記録されていないコードの削除
• 説明のない変数名の変更や構造変更
• コアチームが削除を求めるような抽象化（refactoring-patterns.md を確認）

---

リファクタリング（既存コードの変更）

1. 方針を決める — 何が何に影響するか？

architecture.md を読み込みます。変更を加える前に、影響範囲を把握してください。

2. パターンを調べる — どのパターンが当てはまるか？

refactoring-patterns.md を読み込みます。まず最初にある判断マトリクスを確認してください。 見つけたコードの問題に、適切なパターンを対応させます。その後、実際の変更前後の差分が載っている該当パターンの節を読みます。

• 簡素化パターン（不要な抽象化の削除）
• 統合パターン（Bun から Node への移行）
• 抽出パターン（再利用可能なユーティリティの切り出し）
• 移行パターン（Effect サービスへの移行）
• 削除パターン（未使用コードの削除）
• 安定化パターン（順序や競合状態の修正）
• バリエーションの排除（特殊ケースの削除）

3. 調査 — 既存のユーティリティでこのコードを置き換えられますか？

helpers-deep-dive.md を読み込みます。最適なリファクタリングでは、多くの場合、20 行を 1 つのユーティリティ呼び出しに置き換えます。

4. 確認＋レビュー

実装フェーズの 4～5 と同じです。style-dna.md に続けて review-voice.md を読み込みます。

---

重要な決定事項（常に適用）

• Effect は必須です — すべてのサービスで Context.Service / Layer / makeRuntime を使用します。通常の async クラスは使用しません。
• 1 モジュールにつき 1 つの自己バレル — トップレベルにエクスポート（スキーマ、Interface、Service、layer、defaultLayer）をフラットに記述し、最後に export * as X from "." でファイルを閉じます。利用側は引き続き import { X } from "@/x" → X.Service と記述します。バレル自体が名前空間です。opencode では、ファイル内の export namespace X {} は廃止されました。
• あらゆる場所で Effect Schema を使用します — DTO、イベント、ツールのパラメーターには Schema.Struct + Schema.Schema.Type<typeof X> を使用します。境界スキーマには .annotate({ identifier }) を、フィールドには .annotate({ description }) を指定します。Effect のエラーには Schema.TaggedErrorClass を使用します。ブランド ID には、@opencode-ai/core/schema の Newtype<Self>()("Name", Schema.String.check(...)) を使用します。Zod は境界ツールではなくなりました。
• イベントソース方式の書き込み — 変更は SyncEvent.run → プロジェクター → SQLite を経由します。イベントソース方式ではない機能に限り、DB に直接書き込みます。
• テストでモックを使わない — tmpdir + Instance.provide + 実際のサービスを使用します。モックは外部 SDK に限り使用します。
• 変数名は 1 語にします — state、pending、info、row、cfg、tx のようにします。複数語を使うのは、実際に曖昧さがある場合に限ります。

---

リファレンス一覧

ファイル	サイズ	内容
style-dna.md	18K	必須のスタイルルール、命名、制御フロー、レビューで注意すべき 14 項目
primitives.md	22K	クイックリファレンス：すべてのユーティリティとインポートパス、シグネチャ
helpers-deep-dive.md	~40K	詳細解説：すべてのユーティリティ、すべての使用箇所、使用すべきでない場合
architecture.md	~30K	モジュールマップ、依存関係グラフ、データフロー、ファイル規約
service-module.md	27K	Question と Permission の完全な実装
tool-module.md	28K	ツールの完全な実装、レジストリ、プロンプトループ
test-writing.md	42K	あらゆるフィクスチャパターンを含む、完成したテストファイル 5 件
schemas-and-state.md	36K	SQL テーブル、Effect Schema（Struct/annotate/Newtype）、SyncEvent のフロー、エラー
server-and-routes.md	32K	ルート、設定、プラグイン、プロジェクトのライフサイクル
review-voice.md	~25K	Dax と Aiden による、実際の PR レビューコメント
refactoring-patterns.md	~25K	整理コミットにおける、実際の変更前／変更後の差分