生成・変換・調査・検証など、開発作業を補助するスクリプトの共通ルールを定める。LLMが作るスクリプトにも適用する。保存するかは、次の開発者が何を変更・再実行するために必要かで判断する。
共通規約はDevSpaceで管理し、子repoへ複製しない。各repoには機能固有の生成契約・設計理由・実行手順を残す。Git操作と公開の権限は AGENTS.md、文書の配置は ナレッジの配置と更新 に従う。
既存のコマンド・生成処理・検証runnerで目的を満たせるか確認する。単純な編集は直接変更し、計算・反復・大量変換をまとめる必要がある場合にスクリプトを作る。今回必要な処理を簡潔に表し、将来使うかもしれない汎用CLIや設定機構は追加しない。
一時的な処理にも対象範囲と前提を設ける。複数処理を一行へ圧縮せず、計算・変換・書込みのまとまりが読める形にする。コメントは値の意味や変更時に守る条件を説明し、通常の代入や反復を逐語的に説明しない。
実サーバーの検証は 共通runner を使う。機能固有のfixture配置やシナリオ展開が必要なら、その部分を対象repoに置いてrunnerへ接続する。
| 用途・条件 | 保存するもの |
|---|---|
| フォント・座標・曲線・対応表などを、入力や計算条件から再生成する | 生成元と必要な入力。成果物から調整方法を読み取りにくい場合も、生成元を残す |
| 回帰検証や継続運用で再実行する | 検証・運用スクリプトと前提・入力・期待値。個別機能専用でも保存する |
| 一度限りの移行を別環境でも適用する、または監査に必要とする | 移行スクリプトと適用条件・対象の版・再実行時の扱い |
| 特定の変更前コードを編集する、または今回だけの調査を行う | スクリプトはスクラッチパッドやGit管理外の作業領域に置く。採用したコード・判断・必要な検証記録は、それぞれの保存先へ残す |
利用回数や対象機能の数で保存を決めない。初回でも将来の再生成・再検証に必要なら保存対象にする。一時領域で作り始めたものも、完了時に用途を見直す。会話の記憶やLLMによる再作成を、生成元の保存の代わりにしない。
継続して再生成する場合は、生成元と入力を保守する。成果物には、形式が許せば生成元への参照を付ける。JSONなどコメントを置けない形式では、近くの手順から生成元と出力先を辿れるようにする。成果物の修正が必要になったら生成元へ反映し、再生成して確認する。
一時スクリプトで作った完成コードを直接保守する場合は、完成コードを正本にする。生成物の直接保守へ切り替えるときも、再生成しない範囲と案内を揃える。古い生成スクリプトを更新手順に残すと、撤回した仕様や修正前のコードを再導入するため、現行の保守方法と混同させない。
配布に必要なmcfunction・JSON・画像は、生成元と併せて対象repoへ含める。キャッシュ、取得した配布物、ログ、展開済みシナリオ、検証用worktreeはローカル領域で扱う。外部素材の取得・同梱ではライセンスを確認する。
生成処理は対象repoの scripts/ 配下へ、カテゴリ・機能単位でまとめる。同じ仕様変更で一緒に直す処理・補助モジュール・入力を近くに置く。1機能に1本という前提は置かず、1本でも機能のディレクトリを作る。言語別や生成・変換などの処理種別を第一階層にしない。
Assetでは既存のカテゴリとID付き名称に合わせる。次は、神器に複数の生成処理がある場合の配置例であり、現在のファイル構成や必須の一式を示すものではない。
scripts/
artifact/
0921.celestial_star/
README.md
generate_starfield.py
generate_trails.py
geometry.py
constellations.json
IDを持たない本体機能は、機能名でまとめる。例えば文字幅とボスバーの生成処理を次のように分ける。
scripts/
text/
generate_widths.cjs
bossbar/
generate_tables.py
全神器の登録更新なら scripts/artifact/、特定の神器だけならその配下に置く。scripts/ 直下にはrepo全体を対象とする入口だけを置く。機能専用の補助処理は機能の中に置き、実際に複数機能で共有する契約ができた段階で共通モジュールへ分ける。入力も、独立して編集する必要がある場合に別ファイルにする。
回帰検証は tests/ 側で対応する機能にまとめ、CI固有の処理は既存の .github/ 構成に合わせる。DevSpaceには環境・共通検証を置き、子repoの機能固有スクリプトを集めない。
複数repoへ出力する場合は、入力の契約と生成処理を保守するrepoに生成元を一つ置く。入力・出力先と実行順序を案内し、各repoへ同じ生成処理を複製しない。
新規作成にはこの配置を適用する。規約への適合だけを理由に既存スクリプトを一括移動しない。既存配置を変更するときは、呼出元・CI・生成物内の参照・実行手順を一緒に更新する。
目的、入力、出力、実行コマンド、実行環境と依存、再実行時の上書き・追記・削除を、スクリプトの冒頭か既存文書から確認できるようにする。複数ファイルの関係や実行順序の説明が必要なら、機能ディレクトリのREADMEにまとめる。短いスクリプトの冒頭や既存ナレッジで説明が足りる場合は、新しいREADMEを作らない。
機能固有の生成契約・設計理由は対象repoの既存ナレッジへ置き、実行手順は冒頭・README・既存ナレッジのいずれか一か所に置いて参照する。共通規約や同じ手順を複数箇所へ転記しない。
個人の絶対パスを埋め込まず、自repoはスクリプトの場所や明示した実行ディレクトリから解決する。依存repoの配置は固定の親相対パスとせず、引数や既存設定で対象の作業コピーを指定する。repo直下とデータパック直下も区別し、実行前に入力・出力が意図した作業コピーを指すことを確認する。
依存パッケージの管理場所と準備方法を明記し、別機能や別repoのインストール済み環境を暗黙に借りない。出力に影響する外部データの版・ハッシュ、乱数seed、列挙順を固定し、同じ入力から同じ成果物を得られるようにする。
入力不備や想定外の置換件数を成功扱いにしない。既存ファイルを書き換える処理は、書込み前に可能な範囲で前提を検査する。書込み・削除は対象のファイルや領域に限定し、広い範囲を変更する場合は一時出力との比較やdry-runを使う。途中で失敗した場合は、変更済みの範囲を確認してから再試行する。追記型の処理や入力自体を書き換える処理は、無条件に繰り返さない。
生成後は、生成元と成果物の差分・構文・参照先を確認する。生成したmcfunctionにもIMP Doc・公開範囲・インデントなどの共通規約を適用する。安全に再実行できる処理では、再生成して差分が安定することを確かめる。
検証の期待値は仕様・API契約から決め、検証対象の実装から自動生成しない。生成処理と同じ計算を繰り返すだけのテストを増やさず、変更の影響に応じて境界条件・既知の不具合・入力不備を確認する。シナリオの定型部分を生成する場合も、入力と期待値は仕様から定める。生成差分や構文検査の成功を、実サーバーの挙動やクライアントの表示の成功と扱わない。
- 次の保守に必要な生成元・入力が、一時領域だけに残っていないか確認する。保存対象が対象repoのGit変更一覧に含まれ、不要な一時ファイルを含んでいないことも確かめる。
- 生成元・入力・成果物と、直接保守する範囲の説明を照合する。生成元を保存するだけで同期済みと扱わず、現行成果物との対応を確認する。
- 保存先の機能単位、実行手順、依存、出力先、参照リンクを確認する。移動した場合は呼出元とCIの旧パスも検索する。
- 実施した検証と確認できた範囲を報告する。再生成や実機確認が未実施なら、その状態を区別する。再利用できる知見は ナレッジの採用基準 に従って記録する。