通常のAI開発はDevSpaceから開始し、共通規約・参照指示・知識の更新方針をDevSpaceで一元管理する。子repo単体でAI開発を完結させる運用は推奨しない。子repoのAGENTS.mdは開始位置の案内だけを持ち、コード固有の知識はコードと同じブランチで管理するため各repoに残す。
| 役割 | 正本・案内 |
|---|---|
| 共通規約・対象repoの選択 | DevSpaceの AGENTS.md |
| 環境操作 | DevSpaceの README.md |
| 本体の構造・契約 | TheSkyBlessingの 開発ナレッジ |
| Assetの構造・契約 | Assetの 開発ナレッジ |
DevSpaceの AGENTS.md が、実装・レビュー・調査の依頼内容から必要な詳細文書をAgent自身が選び、判断前に読むよう指示する。ユーザーは普段の作業依頼だけを伝え、文書名や読む指示を毎回追加する必要はない。並列担当には共通規約の所在を渡し、worktreeからDevSpaceの規約を読んだうえで、担当する作業コピーのナレッジへ進ませる。指示を追加・変更した後の読込確認は新しいセッションで行う。
自動で指示に含まれるAGENTS.mdと、そこから参照する詳細文書は区別する。docs/knowledge/*.md の本文を自動展開する設定にはしておらず、AgentがDevSpaceの必読案内から対象repoのナレッジREADMEと関連本文を読む方式である。子repoのAGENTS.mdを通常の必読経路に挟む必要はない。
CLAUDE.md は @AGENTS.md で本文を共有する。今回の対象は TheSkyBlessing と Asset。Asset-AnimatedJava 自体の体系的な知識整理は対象外だが、Asset からの呼出規約は Asset 側で扱う。
Mob／Objectの変更ではAsset側の 型・インスタンス・継承モデル、Effectの変更では対象作業コピーの ナレッジ入口 が案内するEffectの文書を起点にする。本体側の Asset の実行モデル はdispatch、Fieldの保存、contextの退避・復元を扱う。個別関数の手順に加え、親の契約と個体の状態を確認する。
本体の機能追加や領域をまたぐ変更では、本体の抽象構造 から、定義・個体状態・snapshot・寄与と導出値・イベント・呼出 context の境界を確認する。既存のどの拡張点へ変更を載せるか、誰が状態を保存・解除するかを判断するための入口である。配置・解呪・転移・商人・コンテナは World コンポーネント、アイテム・回収・Mob 転送・計算部品は Runtime コンポーネント から、その領域固有の所有・更新・受け渡しを確認する。
必要領域を入口から選び、本文の取得範囲を確認する。truncated が出た一括読取は未取得の範囲を残しているため、ファイル単位・行範囲に分けて再取得する。Assetから本体APIを利用する設計でも、本体の状態・寄与・幾何の案内を適用する。全資料の一括読取を要求するものではない。
実サーバーの検証は 再実行できる機能検証 に従う。成功した最終試行だけでなく、失敗した試行の条件・観測・終了方法と、再試行で変更した条件を実行記録へ保存する。手動で初期化した試験を自然な初期化の検証と扱わず、ログから確認できない原因を断定しない。記録の保存と、ナレッジへの採用は別に判断する。
目的は次回の実装・レビューで判断を助けることである。実装・レビュー・調査・ユーザーの訂正は知見を選ぶ契機であり、毎回追記する理由ではない。採用前に次の3点を確認する。
- 使う場面：後のどの作業で、何の判断が変わるかを説明できるか。
- 根拠と条件：コード・採用済みの設計・ユーザー方針・観測などの根拠があり、適用範囲を説明できるか。未採用の提案や一時的な作業状況ではないか。
- 既存との差：既存の説明に欠落・誤りがあるか。同じ内容なら更新しない。
条件を満たす知見は、個別の記録依頼を待たず作業内で扱う。コード固有の知識は対象作業コピーの既存節へ統合し、共通知識は下記の統合担当へ引き渡す。抽象的な標語だけにせず、構造・契約・原因と、それが設計やレビューにどう影響するかを具体的なコード例で説明する。個別機能に限定された知識でも、その機能を後で変更する判断に必要なら残す。対象の実装を順に言い換えただけの説明は追加しない。
イディオムは「何を実装したいときに使うか」から説明し、成立させる仕組み、適用条件、置換すると失われる性質を残す。個別IDや固定値は実例として結び、値域・実行文脈・対象entity・寿命に依存する部分まで一般化しない。意図の推測は再利用の根拠にせず、確認できた操作と条件から説明する。コメントの古さや既知バグは正しい手本へ混ぜず、必要ならissue・検証記録へ案内する。
実装で得た知見は、追記前に次の順で整理する。個別のIDや秒数を一般的な単語へ置換するだけでは、設計判断の説明にはならない。
- 要求と選択を抽出する。 どんな要求に対して、なぜその構造・API・処理順を選ぶのかを書く。状態を持つ主体、生成・更新・解除の責務、寿命、イベント境界など、その選択を成立させる関係を説明する。
- 適用条件を分ける。 同じ選択が使える条件と、条件が変われば選び直す点を示す。使う場面が分かる見出し・説明を先に置き、ID・数値・個別仕様は根拠となる実例へ結び付ける。個別仕様はその機能の保守に必要な範囲で残し、試験手順と実測は検証記録へ分ける。
- 別の要求へ当てはめる。 代表的な知見について、元の実装とは条件を変えた適用例と適用外の例を考え、本文だけで採用・不採用と必要な変更を判断できるか確認する。例えば装備解除後も続く待機時間の説明なら、装備中だけ進む場合や、未接続中も実時間で進む場合へ同じ処理を使ってよいか判断する。答えるために会話の記憶や未記載の前提が必要なら本文を直す。
この確認は説明の適用範囲を確かめるもので、仮想例での実装成功・ゲーム内動作の検証とは区別する。確認のために考えた例や問答を毎回ナレッジへ蓄積しない。本文には判断を支える条件を反映し、確認方法と結果は完了報告や必要な検証記録へ残す。個別機能にしか成立しない知見を無理に共通化せず、その機能の理由・制約として整理する。
APIや実行基盤の挙動は提供側のナレッジを正本とし、利用側には実装上の選択・実例と正本への参照を置く。利用側へ処理順や制約の全文を複製して、別々の現行仕様として維持しない。
契約の変更や回避策の追加・撤去を扱うときは、対応する提供側と利用側の作業コピー・コードを照合する。基準commitだけでは未コミット実装の根拠にならない。旧版への回避策を残す場合は、成立する版または実装の条件と、条件が変わったときに再確認する判断を記す。検証成功はその対象コードに対する証拠であり、違う版を前提とした説明の正しさまで証明しない。
更新時は正本から参照される利用例に加え、影響するAPI名・状態名・旧説明を対象repoのナレッジから検索し、本文・実例・sourcesの矛盾を直す。リンクが存在することだけで整合確認を終えない。適用する作業コピーを確認できない知見は現行契約と断定せず、確認済みの条件に限定する。
採用する結論には、次の情報を判断に必要な範囲で添える。項目を埋めるために調査結果や未確認事項を作らない。
- 適用範囲：対象パスや作業内容。個別の神器・Mob の事情を全体の禁止事項にしない。
- 理由と失敗例：何が壊れるのか、どの実行主体や一時データに依存するのか。
- 現行の実例：repo 内のファイルへの相対リンク。API は引数・戻り値・呼出前提・後始末を確認する。
- 出典と結論：コードや PR / レビューコメントの直接参照、採用状況、現行コードとの対応。ユーザー方針とコード上の事実を区別する。
- 確認範囲：結論を支える確認方法と限界。試行の全履歴や成功件数を本文へ転記しない。
| 内容 | 保存先・扱い |
|---|---|
| 共通の開発規約・AIへの参照指示 | DevSpaceの AGENTS.md。子repoへ複製せず、由来となった会話や修正履歴は載せない |
| repo共通の用語・翻訳・表記の指定 | DevSpaceの 用語と表記。AGENTS.mdには参照指示を置き、用語ごとの指定はリンク先へ集約する |
| Issue・PR本文の目的・記載内容・確認観点 | DevSpaceの Issue・PR本文の書き方。作成・更新時に参照し、子repoへ複製しない |
| 両repoに適用できるコマンドの意味・数値・実行文脈のイディオム | DevSpaceの 共通イディオム。子repoにはAPI固有の契約と利用例を残す |
| 開発用スクリプトの作成・保存・配置・再実行・検証 | DevSpaceの 開発用スクリプトの作成と保存。AGENTS.mdには要点と参照指示を置き、各repoには機能固有の契約・設計理由・実行手順を残す |
| 知識の採用・配置・更新手順 | DevSpaceのこの文書 |
| 環境操作・共通検証手順・環境の設計理由 | DevSpaceの README.md、docs/runtime-verification.md、docs/development-environment-design.md の該当節 |
| コード固有の構造・契約・原因・採用済みの設計理由 | 対象repoの docs/knowledge/ の既存の該当節。コードと同じ作業コピーで更新する |
| コード固有の結論の出典・採用状況・確認範囲 | 対象repoの sources.md の該当項目。必要なときに該当節を読む索引とし、全文の読取や毎作業の更新を必須にしない |
| 検証の前提・操作・期待値と実測 | 前提・期待値は対象repoのシナリオ、実測・失敗・再試行は実行記録。共有する検証報告が必要なら検証文書へ置く |
| 未採用案・比較検討 | 継続する設計作業で保存する必要がある場合だけ docs/design/ 等の別文書へ。現行仕様と分け、通常の必読には含めない |
設計メモにも会話を逐次転記せず、現在の課題・選択肢・判断に必要な根拠をまとめる。保存目的がない一時的な思いつきはファイルにしない。「未検証」「提案」とラベルを付けるだけでナレッジ本文への掲載を認めるものではない。一方、再利用できる既知の制約や不具合は、発生条件と根拠を示して本文に残す。
新しい領域を追加するときだけ README の案内を増やす。sourcesや設計メモの存在を、毎回読む必要性と取り違えない。領域文書とsourcesへ同じ結論・経過を二重に書かない。
記録先は発見場所や読者の数ではなく、内容の責務で選ぶ。mcfunctionの記法・IMP Docの可視性・Git操作等の共通規約はDevSpaceで一度だけ更新する。神器固有の発動条件やID配置はAsset、本体のAPI契約や内部処理はTheSkyBlessingに置く。
たとえば本体APIの契約はAssetからも使うが、そのために契約の全文を両repoへ複製しない。本体に正本を置き、Assetには固有の利用例と参照先を残す。提供側の変更が利用側の説明にも影響する場合は、その利用例を照合・訂正する。共通規約も子repoに写さず、各repoの本文には必要な実例を残す。worktreeでは依存repoの配置が異なるため、固定の親相対パスを仮定せず引き渡された参照先を使う。
レビューは過去の文脈を含むため、コメントをそのまま現在の仕様としてコピーしない。実装変更で規約が古くなった場合は、該当本文と出典の現行対応を一緒に更新する。
ProjectTSB Wiki の設計意図・作成規約も根拠に含める。本体の照合記録 と Asset の照合記録 にページ別の採否を記録している。Wiki に明記された規約、現行実装との差、コードから追加した補足を区別し、実装が規約を強制しないことだけを理由に規約を取り消さない。
共有DevSpaceの追跡ファイルの編集とGit操作は、一人の統合担当が編集開始からpush完了まで担当する。並列作業の開始時に担当と連絡先を各担当へ渡す。別々に開始したセッションが同じDevSpaceを使う場合も、統合担当を共有する。担当の交代時には未処理の候補・未公開差分を引き継ぎ、前任と後任が同時に書き込まない。単独作業ではそのセッションが担当する。担当が不明な並列セッションは共有ファイルを編集せず、候補の引渡しを準備する。
- 発見した担当が引き渡す。 次の判断をどう変えるか、適用条件、根拠となるコード・文書とその版、DevSpaceの更新先・修正文案を渡す。子repoの未マージ差分に依存するかも示す。既存のタスク連絡・結果報告を使い、共通知識の候補を子repoのナレッジやsourcesへ仮置きしない。
- 統合担当が採否を判断する。 採用基準に加え、子repoの未マージ変更がなくても成立することを確認する。例えば公開範囲の確認手順は共通知識、新しいEffect APIの具体的な動作はそのAPIと同じ子repoに置く。既知の内容は追記せず、条件が必要な知見を無理に一般化しない。
- 採用した内容を既存節へ統合する。 共有DevSpaceの
mainを使い、知識更新だけのブランチ・worktreeは作らない。更新前にbranch・upstream・作業ツリー・index・未pushコミットを確認する。既存差分や別担当のstagingを巻き込まず、対象の文書・差分だけをstageし、文書間の整合・参照先とgit diff --check、stage済み差分を確認する。 - 知識更新だけをcommit・pushする。 AIのコミットメッセージと確認 に従ってコミット前後に件名を確認し、
mainからorigin/mainへ通常のpushで逐次公開する。この範囲では追加の公開依頼を待たない。無関係な未pushコミットも公開対象に含まれるため、送信範囲まで確認する。既存変更を安全に切り分けられない場合や、別ブランチ上の場合は、reset・stash・checkoutを強行せず未公開として引き継ぐ。pushが拒否された場合はfetchして差分を照合し、安全に統合できる場合だけ再検証して再送する。force pushしない。 - 結果を返す。 更新先、採否と理由、commit、pushの成否を発見した担当へ返す。現在作業中の担当にも関係する規約変更は、対象節を知らせて読み直してもらう。ファイルの更新だけで既存セッションの理解も更新されたとは扱わない。
統合担当が不在・受領未確認などで引渡しが完了しない場合は、共有DevSpaceの .runtime/knowledge-handoffs/ に担当・タスクを識別できる一意の名前で候補を保存し、完了報告にそのパスを含める。他担当のファイルを上書きせず、統合担当は作業開始時と完了前に未処理分を確認する。採否・公開状態を記録し、処理完了した引渡し記録は整理する。これはGit管理外の引渡し用記録で、採用済みナレッジや作業日誌ではない。読み取り専用の依頼ではファイルを作らず報告だけにする。
逐次公開の対象はDevSpaceの共通知識文書であり、子repoの変更やDevSpaceのスクリプト・環境設定の公開許可ではない。環境実装を並列変更するときはDevSpaceの実装用worktreeを分ける。担当による直列化の運用であり、Gitのlockや検証runnerが文書の同時編集を防ぐ仕組みではない。
- 候補を「使う場面・根拠と条件・既存との差」で選ぶ。既存の説明で足りる場合や作業状況しか増えていない場合は追記しない。
- 該当本文を現行の結論へ更新し、古い説明と重複を整理する。訂正の経過を日付付きで追加するだけにしない。採用した設計理由は残すが、未採用案や試行記録を本文へ混ぜない。
- 更新差分を読み、元の会話を知らない開発者が判断に使えるか確認する。再利用する知見は 別の要求への適用、依存する契約は 提供側と利用側の整合 を確認する。コード・根拠リンク・他文書との対応も確認し、新たな保存先や必読を増やす場合は、その必要性を見直す。
- 完了報告には更新先、または更新不要の理由を短く示す。共通知識は引渡し・採否・commit・pushの状態を区別し、未処理の候補を残した場合は引渡し先を示す。報告を埋めるためにファイルを更新しない。明示的に編集禁止の作業なら、採用基準を満たす候補だけ保存先とともに報告する。
この運用は AGENTS.md の指示に従って作業中の Agent が記録する方式であり、記録漏れを機械的に検出・強制する仕組みではない。作業外に新しく付いた GitHub コメント等を自動収集する処理も、この運用には含めない。完了報告に更新先を含めることで、実際に記録されたか確認できるようにする。
TheSkyBlessing / Asset は独立 Git リポジトリなので、各repoの指示・ナレッジはそのrepoの変更として共有する。DevSpaceのコミットだけでは含まれない。共有前に各repoの差分とコミット対象を確認する。過去に入口をコミットしていても、その後の未コミット修正は含まれない。pushは別操作であり、ローカルへの保存を他環境への配布済みとは扱わない。
新しい worktree は、元の作業ツリーにある未コミットの AGENTS.md やナレッジを自動では引き継がない。並列作業へ渡す前に、対象 worktree の入口・本文・必要な起動設定が揃っているか確認する。共有する状態は各 repo の履歴へ含めるのが基本で、未コミット状態を使う必要がある場合は、対象と基準を明示して必要な差分・未追跡ファイルを作業コピーへ渡す。既存の変更を上書きしたり、元 repo へのリンクで編集内容まで共有したりしない。以前の worktree 読込検証も、未コミット文書を検証先へ明示的にコピーした条件である。
worktree は、元の repo と作業コピーの場所を互いの絶対パスで記録する。DevContainer の /workspaces/DevSpace とホストのように、同じフォルダーを別のパスで開く環境では、一方で作った worktree を他方の git で操作できない。作成していない側では git status が not a git repository で失敗し、git worktree list は prunable と表示する。この状態で git worktree prune を実行すると、共有フォルダー上の管理情報が消え、作成した側でも作業コピーとの対応が切れる。git gc も、その worktree の index が既定で3か月以上更新されていなければ、同じ prune を行う。ブランチ上のコミットと作業ファイルは残るが、その worktree の index（stage 済みの変更）・HEAD・reflog は失われ、detached HEAD で作ったコミットは到達できなくなる。worktree は、それを操作する環境で作る。別の環境に残す worktree は git worktree lock で prune と gc の対象から外せる。
別の環境から worktree を一時的に扱う場合は、GIT_DIR に元の repo の .git/worktrees/<名前>、GIT_WORK_TREE に作業コピーを、その環境のパスで指定する。export すると、ほかの repo を対象にした git やスクリプトも同じ worktree を操作する。この状態で一時 repo を作るテストなどが git init を実行すると、元の repo の共有の config に core.worktree が書き込まれる。そのパスがある環境では、通常の checkout の git がその作業コピーを作業ツリーとして扱い、パスがない環境では fatal: Invalid path で止まる。コマンドごとに前置きで指定し、export しない。書き込まれた場合は、repo の外から git config --file <repo>/.git/config --unset core.worktree で消す。git 2.48 以降の --relative-paths で作ると両方から使えるのは、repo と worktree の相対位置が両方の環境で同じ場合に限る。この方式では repo に extensions.relativeWorktrees が設定され、2.48 未満の git ではその repo を開けなくなる。使う前に両方の環境の git の版を確認する。
並列の実装では担当するrepo・ファイル・共通ID／alias／tagの変更責任と、統合担当を分ける。コード固有の知識は各作業コピーへ残してコードと一緒に統合し、共通知識は上記の手順でDevSpaceへ逐次反映する。子repoのマージを共通知識の公開待ち条件にはしない。共通サーバーの設定・検証順序は README の起動手順 に従う。
文書更新時は、相対リンク、例のパス、出典との対応、入口からの必読経路を確認する。通常運用の読込確認はDevSpaceを開始位置とする新しいAgentセッションで行い、対象repoのナレッジREADME・関連文書へ進むことを確認する。worktree担当はDevSpaceの規約を受け取った条件、子repoを直接開いた場合はDevSpaceへの開始位置の案内を確認する。開始時の指示を答えさせる確認は指示の受渡しだけを測るものであり、文書の存在やその回答を自発的な参照の証拠と扱わない。実施結果は 知識の検証記録 に記載する。
検証では、開始時に渡る指示の確認、誘導なしの文書参照、読ませた後の適用を区別する。自発的な参照を測る場合は、検証プロンプトに文書名、読む指示、必読文書を答える指示を加えず、通常の作業依頼から実際の読取ログを確認する。読むよう指定した検証の結果を、通常依頼での自発的な参照の根拠にしない。