hakoniwa-world

Imported from Mamiki765/hakoniwa-world (AGENTS.md). Install upstream with npx skills add Mamiki765/hakoniwa-world. Copyright stays with the author.

AGENTS.md

このファイルの目的

このファイルは、hakoniwa-worldで作業する実装・調査Agentの恒久的な行動原則を定める。

本文はOwnerが直接確認できる日本語を正本とする。 コード上の識別子、コマンド、ファイルパスなどは必要に応じて英語表記を使用してよい。

個別機能の仕様、特定releaseの事情、過去の事故、具体的なテスト手順はここへ書かない。 それらはcode、test、architecture、operations、release文書、Git履歴を正本とする。

1. Ownerの指示と解釈

• Ownerが明示した目的、制約、作業範囲、停止条件を優先する。
• Ownerの指示を、実装上都合のよい別の意味へ読み替えない。
• 明示された制約を回避するため、制約対象と実質的に同等の仕組みを別の場所や別authorityとして新設しない。
• Ownerの要求と既存設計が衝突する場合、独自解釈で迂回せず作業を止め、衝突点と選択肢を報告する。
• 依頼されていない機能、cleanup、再設計、将来対応を「ついでに」追加しない。
• Ownerが終了させた互換性や非目標を、Agent判断で復活させない。

2. 作業範囲

• アプリケーションのruntime、schema、frontend、testsは原則としてproduct/配下で扱う。
• rootの設定・文書・CIは、依頼された作業に直接必要な場合だけ変更する。
• 一つのPRへ無関係な機能、広範なrefactor、別systemの仕様変更を混ぜない。
• 必要な変更が当初の小さな境界を超える場合、実装を続ける前にOwnerへ報告する。
• Ownerが使用を認めたrepositoryでは、通常の作業branchの作成・commit・push、初回PR作成、PR title/body更新、review comment投稿、review修正のcommit・再pushを通常の開発作業として進める。review可能な状態までの反復更新に個別のOwner確認は不要であり、使用可能なForgejo・GitHubで権限を分けない。migration fileを作業branchで作成・commit・pushすることも同様に扱う。
• release/* branchは、Ownerが対象releaseの作成を明示したときだけ作る。通常の作業branch作成権限からrelease作成を推定しない。自動同期先でも別途作成せず、指定された開発正本と同期方向を守る。
• mainへの直接commit/push、PR merge、production deploy、production DB操作・migration適用、OCI上のproduction変更、production user dataへの補填・変更はOwnerの明示許可なしに行わない。

3. 正本と文書

作業開始時はproduct/docs/handoffs/current-status.mdとdocs/README.mdを読み、依頼に関係するdocs/open-questions.mdのgate、現行contract、code・schema・migration・testsへ進む。未完作業は現在地から案内する予定表を使い、旧統合handoffや全docsを一括で読まない。

• 現行仕様・設計・運用、Owner採用済みの未完作業、未決の構想、完了履歴を分ける。実装済みでも現役の仕様書・runbookはarchiveへ送らない。
• archive/配下はOwnerの明示指示がある対象だけ閲覧・検索する。通常検索から除外し、古いリンクの追跡や一括読込で間接的に戻さない。Git履歴もこの制限の迂回に使わない。
• 未処理の監査候補は予定側で保持する。historical文書、audit文書、roadmap、future proposalをcurrent authorityとして扱わない。
• handoffはOwnerの明示指示なしに編集、再生成、整形、commitしない。
• ファイル名や更新日時だけで正本かどうかを判断しない。文書とcurrent code・schema・accepted ADRの矛盾は報告し、黙って仕様を変更しない。
• 詳細仕様をAGENTS.mdへ複製しない。

4. Production dataとmigration

• production dataを削除、reset、または黙って別の意味へ再解釈しない。
• 既存migrationはappend-onlyを原則とする。
• Ownerがproduction baselineを明示していない限り、既存migrationを変更、削除、統合、rebaselineしない。
• repositoryの状態、application version、schema dump、Git履歴だけをproduction適用状態の証拠にしない。
• 未適用migrationを整理する場合は、Owner確認済みproduction baselineと、fresh install・supported upgradeの検証を根拠にする。
• persisted dataやcanonical identityを変更する場合、既存データの変換、retry、idempotency、auditへの影響を確認する。
• releaseを跨ぐ未解決Turnを自動retryしない。既存のmanual retry契約とaudit記録を維持する。
• production操作をsubagentへ委譲しない。

詳細なdeploy・backup・restore・migration手順はoperations文書を正本とする。

5. Version管理された設定とRuleset

詳細なRuleset authoringは product/docs/architecture/ruleset-authoring.md を正本とする。

分類の要点だけを次のように扱う。

• Behavior: 処理経路、identity、selector、順序、timing、state transition、RNG、解釈方法
• Data: 既存Behaviorへ渡す数値や入力値
• Flavor: gameplayや永続状態を変えない名称、説明、表示文言

運用上は次を守る。

• productionで実際に使用されたimmutable snapshotを上書きしない。
• source名、変数名、publishedという表記だけでfreeze状態を推測しない。
• 未release設定の変更可否は、Owner確認済みproduction baselineと現在のrelease境界から判断する。
• release開始時にOwner確認済みproduction RulesetをNとする。semantic changeが不要なら、そのreleaseはNを維持する。
• 1 releaseで導入してよい新Rulesetは原則N+1の1世代までとする。Ownerの明示承認なしに2世代以上増やさない。
• release未完了中の追加機能、追加PR、stabilizationは同じN+1 draftへ統合し、feature、PR、migration単位でN+2以降を作らない。
• 2世代以上が必要だと判断した場合は実装を止め、理由と選択肢をOwnerへ報告して明示決定を得る。
• Ruleset version budgetはsubagentにも継承し、subagent判断で追加世代を作らせない。
• versioning上の制約を避けるため、Ruleset外に第二のdefinition authority、第二のcatalog、第二の設定体系を作らない。
• UIやtarget contextを分離する必要があっても、version authorityまで自動的に分離したと解釈しない。
• 判断が明確でない場合は、実装前にOwnerへ確認する。

特定のRuleset version、特定release、特定PRの事情はAGENTS.mdへ記載しない。

6. Design gate

• 実装前に、依頼範囲に関係するdocs/open-questions.mdの項目を確認する。
• Required beforeへ到達したOpen項目を、Agentが暗黙に決定したり迂回実装したりしない。
• Open項目に該当する場合、実装を止め、選択肢と影響をOwnerへ提示する。
• Deferred項目は早期実装せず、必要最小限のextension boundaryだけを残す。
• Ownerが既に決定したcontractをsubagentやreviewerが再解釈しない。

7. 実装の再利用

• 新しいvariantを実装するときは、まず既存のcanonical runtime pathを確認する。
• 既存pathを再利用し、固有の差分だけを局所化する。
• Item、怪獣、command、facilityなどが異なるという理由だけで、専用execution engineやparallel subsystemを作らない。
• 別pathが必要なのは、ordering、RNG、transaction、lock、persistence、eventなど実行契約そのものが異なる場合に限る。
• 小さな差分を理由に、将来用のgeneric frameworkを先行実装しない。
• 同じ責務の判定・definition解決・projectionを複数箇所へコピーしない。
• 共通contractが実在するときだけ、小さく明確なshared abstractionへ集約する。
• canonical identityをnullable化したり代替identityを追加したりする場合、局所的なschema変更として扱わず、そのidentityを読む全経路を横断確認する。

8. Testとreview

Testとreviewは、故障時の影響に比例して重点を置く。特に次を優先する。

• player data、資産、進行の破壊や回復不能な不整合
• 二重決算、経済破壊、transaction、retry、idempotency、concurrency、lock
• security、authorization、他人の資産操作
• persistence・migration・installの整合性
• 主要なproduction gameplayとoperator経路の停止
• 過去に実際に発生した重大なregression

次を守る。

• testは仕様と故障検出のcontractを検証する。既存testやcommentからOwner intentを逆算せず、恒久contractと扱わない。
• 説明文・空白・DOM構造/順序・class順・内部名・SQL表記・catalogの偶然の件数・設定写経を原則追加しない。例外は防ぐ故障をtestまたはPRに明記する。
• 固定値を一律禁止しない。DB型・制約、認可・秘匿、transaction rollback・同seed retry、スケールの単位・境界、消費・付与個数、欠測と0、本人とPTの分離、前後の資産・進行保持など、仕様上必要な保証を残す。SQL数・履歴非走査の性能contractも維持する。
• UIは意味で要素を選び、ラベルと値の対応・表示配線をfixtureで検証する。実catalogの名称期待はcanonical resolverを参照し、説明文やセル順を固定しない。
• 新規・変更testのreviewでは、contractを保った文言・空白・表示順・SQL表記の変更なら通り、対象の故障なら落ちることを反証や局所mutationで確認し、未確認範囲を示す。
• testの新設・拡張には、到達可能な操作またはsupported upgrade、具体的な故障、既存代表で検出できない理由が必要である。不足は既存代表の最小限の拡張・置換を優先し、独立した責務・失敗条件だけを別caseにする。新機能も同じ基準で判断し、不安だけで追加しない。過去事故は必須条件にしない。
• この基準はfile・method、provider、loop、assertion、別layerにも適用する。同じ故障しか検出しない組合せや無意味なパラメータ全列挙は代表境界に絞り、必要な保証の網羅性は維持する。source横断確認を全経路へのtest追加義務にしない。
• UIを迂回できる外部入力の認可・安全性、正常操作の境界、supported upgradeの既存データは到達不能な異常と区別する。DB直書きだけの到達不能状態、unsupported history、理論上の整数限界のためにtestを増やさない。重要な故障を守る代表には必要なコストを認めるが、高影響だけで全異常系を必要扱いしない。
• 依頼範囲の仕様変更で不要になった保証は削除・置換する。ゼロベース見直しでも必要な保証を確認し、既存保証の全維持や不要な代替testを前提にしない。件数の維持・減少だけを品質の根拠にしない。
• focusedから影響に必要なtestとstatic checkを選ぶ。必要な確認が通ったら終了し、新たな変更・失敗・具体的な未解消懸念がない限り拡大・反復しない。未実施の確認は報告する。
• push/PRの権限とCIコスト管理を分離する。高コストCIがpushごとに動く環境では無意味な細切れpushや小修正ごとのrepository-wide CI要求を避ける。自動起動しない環境では、push節約のためにreview用の共有・更新を止めない。
• repository-wide回帰はexact-head CIを最終authorityとし、同じtest identifier集合を全件実行するPHPUnitは原則CIへ委譲する。localの補完はmigration、concurrency、環境差、CI failureなど具体的な不足に限る。source・dependency・test設定が同じなら全PHPUnitを重複実行しない。一時調査の恒久test化は別に判断する。

Review findingは、supported production pathからの到達可能性と、上記の品質基準またはcurrent player・operatorへの具体的な回帰を示す。好み、unsupported history、DBやrequestで拒否される不可能状態だけをP1/P2としない。test追加を求めるreviewも、到達経路・故障・既存確認の不足を示す。

具体的なtest command、suite構成、CI shard構成はComposer設定とtesting文書を正本とする。

9. Subagent

• boundedで低riskな調査、機械的編集、focused failure調査、文書整合確認、独立regression確認はsubagentへ委譲してよい。
• 利用可能な場合、Lunaをこの種の作業の既定subagentとして使用してよい。
• architecture、Owner intent、Ruleset・migration境界、production安全、cross-cutting integration、最終review判断はmain agentが保持する。
• subagentはOwner contractを再解釈、拡張、迂回してはならない。
• main agentはsubagentの成果を確認してから採用する。
• production mutation、破壊的DB操作、未決のOwner判断は委譲しない。

10. Referencesとencoding

• _references/配下はread-onlyとする。
• _references/のファイルを編集、整形、rename、削除、commitしない。
• third-party実装を直接翻訳・複製せず、必要な挙動だけを独立して実装する。
• third-partyの画像、文章、相当量のcodeを、出典・再配布条件を確認せずproduct/へコピーしない。
• 明示的に再配布可能で、出典・配布条件を記録した小規模なUI/theme素材は、frontend release assetとしてproduct/へ収録してよい。
• 新規code、文書、DB text、API、user inputはUTF-8を使用する。

11. AGENTS.mdの保守

• AGENTS.mdには、長期間再利用できる行動原則だけを書く。
• 特定version、特定release、PR番号、固有機能名、過去の個別bug、一時的な回避策を追加しない。
• 過去事故の教訓を残す場合、固有名詞や事件経緯ではなく汎用原則へ抽象化する。
• 数値、仕様、手順、コマンド一覧、テスト表は、それぞれのcode・test・architecture・operations文書へ置く。
• 新しい事故が起きるたびにお守り文言を追記しない。既存原則へ統合するか、code・constraint・regression testで防止する。
• 更新時は単純追記ではなく、重複や古い記述を削除して全体を短く保つ。