Skip to content

AGENTS.md

Latest commit

 

History

History
420 lines (306 loc) · 26.1 KB

AGENTS.md

File metadata and controls

420 lines (306 loc) · 26.1 KB
Raw

プロジェクト ポリシー

アプリケーション・フレームワーク

https://github.com/OpenTouryoProject/OpenTouryo/

と、ソレを使用したサンプル・アプリケーションの開発エージェント用。

環境のセットアップ・ビルド・検証の手順は root/Readme.ja.md を参照。 本書は、その上でエージェントが守るべきことと、どの文書を見るかを示す。

プロジェクト共通の投稿規約は Contributing.ja.md に従う。 コメント量の目安、クロスコンパイルと下位互換の方針、ブランチ運用（git-flow）、 "プルリクエスト" の粒度は、人もエージェントも同じ規約による。 本書は、そこに書かれていないエージェント固有の制約を扱う。

手順を思い出したいだけなら CHEATSHEET.md を見る。 検証・リリース・VB ビルド・ツール・規約の要点と、よく踏む落とし穴を 1 枚にまとめてある。 理由や判断が要ることは書いていないので、迷ったらそこからリンク先へ辿ること。

Git 操作は行わない（状態を変える操作をしない）

成果物の検収は人が行う。 エージェントは作業結果をワーキング ツリーに残すところまでを担当し、 Git 操作は人が手動で行う。

したがって、指示がない限り次を実行してはならない。

  • git add / commit / push（検収前・未レビューの変更を確定・送信しない）
  • git checkout / switch / branch / reset / restore / stash（人の作業状態や未保存の作業を壊す）

参照系は制限しない。 何を変更したかを正確に報告するために必要なため、次は自由に実行してよい。

  • git status / diff（--cached 含む）/ log / show / ls-files / check-ignore / blame

作業が完了したら何を変更したかを報告するに留める。コミットの要否とタイミングは人が判断する。

状態を報告する直前に、必ず取り直すこと。 前のターンの出力や記憶から書かない。

git status --porcelain                      # 未コミットの変更
gh issue view <番号> / gh pr view <番号>    # Issue / PR の状態
gh api ...                                  # 設定・アラートの状態

人はエージェントの報告とは独立にコミットし、Issue や PR を操作する。 数ターン前の状態は、高い確率で古い。 古い一覧を出すと「まだ残っている」と誤認させ、検収の判断材料そのものが誤りになる。

参照系は制限していないので、回数を惜しむ理由はない。 0 件なら「ワーキング ツリーはクリーン」と書く。前回の一覧を再掲しない。

GitHub 操作は gh で行う

Issue の調査・起票・コメントは、gh コマンドで実行してよい（ブラウザ操作を人に依頼しない）。 上記の「Git 操作は行わない」はワーキング ツリーとコミット履歴に対する制約であり、 GitHub 側のやり取りは対象外。

gh issue view <番号> --repo OpenTouryoProject/OpenTouryo
gh issue list --repo OpenTouryoProject/OpenTouryo
gh issue comment <番号> --repo OpenTouryoProject/OpenTouryo --body-file <path>
gh issue create --repo OpenTouryoProject/OpenTouryo --title <title> --body-file <path>

ただし公開リポジトリへの投稿は取り消しにくいため、次を守ること。

  • 投稿前に文面を提示し、承認を得てから実行する。 承認なしに投稿しない
  • 本文は一時ファイルに書き、--body-file で渡す（改行・記号の欠落を避ける）
  • 投稿後は URL を報告する

テンプレートは自動では適用されない。読んで、その構成に沿って書くこと。

gh issue create / gh pr create の --template は「エディタで編集する前提の 開始テキスト」であり、--body-file と併用すると本文で上書きされる。 エージェントは --body-file を使うため、テンプレートは効かない。

.github/ISSUE_TEMPLATE/bug.md          不具合
.github/ISSUE_TEMPLATE/enhancement.md  機能追加・改善
.github/ISSUE_TEMPLATE/quality.md      品質改善（リファクタリング・規約・CI・文書）
.github/pull_request_template.md       PR

テンプレートは任意（blank_issues_enabled: true）だが、 「利用者への影響」は、無いなら「無し」と明記する。 空欄だと、確認したのか未確認なのかが読み手に分からない。

セキュリティの指摘は、公開される前に確認を取る

SECURITY.md / Security.ja.md のとおり、 セキュリティの問題は公開の Issue に書かない。 報告は Private vulnerability reporting（非公開の security advisory）で行う。

https://github.com/OpenTouryoProject/OpenTouryo/security/advisories/new

見落としやすいのは、Issue 以外の経路で公開されることである。 ワーキング ツリーに書いたものは、コミットした時点で公開になる。 ANALYSIS.md・README・コード中のコメント・コミット メッセージ・PR の本文も同じで、 未修正の弱点をそこに書くことは、公開の Issue に書くのと同じ効果を持つ。 「記録として書いただけ」は、公開しない理由にならない。

したがって、未修正のセキュリティ上の弱点を見つけたら、次の順で進める。

  1. まず人に報告する。 どこに書くか（公開の文書 / 非公開の advisory）を決めるのは人である
  2. 合意を得るまで、攻撃の手順や再現の具体を、ワーキング ツリーのファイルに書かない。 書いてよいのは「どの関数で、どの確認が抜けているか」まで
  3. 非公開の advisory の番号（GHSA-…）は、公開ファイルに書かない。 存在そのものが分かるため
  4. 公開の Issue として起票してよいかは、文面を見せて承認を得る（この節の上の規約と同じ）

修正と同じコミットに入るなら、文書に書いてよい。 その時点で攻撃は成立しない。

利用側のリポジトリで見つけた問題でも、原因が Open棟梁 側なら、報告先は Open棟梁 の advisory である。 サンプル アプリケーション側の文書に書くと、そこで公開されてしまう。

依存パッケージの脆弱性を見つけたら（#610）

ビルドの警告（NU1901〜NU1904）を、件数として流さない。 ビルドは成功扱いなので、 誰かが拾わない限り直らない。Dependabot は推移的な依存を見ず、直接の依存でもアラートが遅れることがある （#610 の時点で、レビュー済みのアドバイザリから 1.5 日経ってもアラートが出ていなかった）。 仕組みは BUILDING.md 13 節。

見つけたら、Issue を起こさずに、その場で直す。 施主の方針である（2026-10-15）。 先に直してしまえば、Dependabot の PR（Bump X from A to B。deps 経由の流れ）も発生しない。 公表済みの CVE（依存パッケージ側の脆弱性）は公開情報なので、コミットや文書に書いてよい （Open棟梁自身の弱点ではない。上の「セキュリティの指摘」とは扱いが違う）。

  1. CheckVulnerability.ps1 -Detail で確かめる。 ビルドの警告は restore のときにしか出ないので、それに頼らない。 ビルドの後に回す（restore 結果が無いと推移的な依存を見られない）
  2. 報告の冒頭に書く。 深刻度が high / critical なら、作業中の本題より先に伝える
  3. 既に Dependabot の PR があれば、そちらに乗る（gh pr list --search "Bump <パッケージ名>"）。二重に直さない
  4. 本題とは別の変更として直す。 施主がコミットを分けられるよう、報告で変更ファイルを分けて示す
  5. CheckVulnerability.ps1 で 0 件になったことと、変えた範囲の検証（SelectTargets.ps1）を報告する
依存 直し方
直接 修正された版へ上げる（同じ系列の修正版。-IssueDraft の「修正された版」列に出る）
推移 引いているパッケージを上げる。上がらなければ、修正された版を直接の依存として足して引き上げる（Samples4NetCore が System.Security.Cryptography.Pkcs で行っている）

版を変えたら、ComparePackage.ps1 / CompareRedirect.ps1 も見る（net48 は packages.config・csproj・bindingRedirect の 3 か所が揃う必要がある）。 基盤（NuGet で配布するパッケージ）の依存を変えるなら、nuspec の依存の版も合わせる。 bindingRedirect の調整は利用する側の裁量なので、版を上げること自体を止める理由にはならない。

その場で直せないとき（修正版が無い、上げると壊れる、範囲が大きすぎる）だけ Issue にする。 -IssueDraft <パス> で下書きを作り、文面を見せて承認を得てから投稿する（上の「GitHub 操作は gh で行う」）。

GitHub Actions を書き足すとき

ワークフローはエージェントが書き足すことが多い。厳し目に倒すこと。

  • permissions: を必ず書く。 既定（read）に頼らない。 何を必要としているかが、ファイルを見て分かる方がよい
  • 第三者製のアクションは SHA で固定する。 @v7 のようなタグは作者側で別のコミットへ付け替えられるため、 こちらが何も変えていなくても動くコードが変わる
  • pull_request_target を使うなら、PR のコードを checkout しない。 ベース側の定義を書き込み権限付きで動かすトリガであり、 PR に任意のコードを書ける相手へ権限を渡すことになる（pwn request）
  • 新しいアクションを増やすときは、本当に必要かを先に検討する

現状と方針は GitHubUsage.md 3 節・8 節。

このリポジトリでは OsscJpDevInfra アカウントを使用する。 gh auth status に複数のアカウントが登録されていることがあるため、 投稿前にアクティブなアカウントを確認すること。異なる場合は gh auth switch で切り替える。

gh auth status                        # アクティブなアカウントの確認
gh auth switch --user OsscJpDevInfra  # 異なる場合は切り替え

Issue のクローズ・ラベル変更・アサイン、PR の作成やマージは人が行う。 これらは成果物の検収と同じ扱いとし、エージェントは提案に留める。

PR のレビューは、--comment だけ行ってよい。

操作 誰が行うか
gh pr review --comment エージェント可（文面を提示し、承認を得てから）
gh pr review --approve / --request-changes 人のみ。検収に当たる
PR の作成・マージ 人のみ

--comment は COMMENTED として記録され、必須レビューを満たさない。 reviewDecision は REVIEW_REQUIRED のまま変わらないので、 マージを進めてしまう心配は無い。

承認が必須レビューとして数えられるのは write 以上の人だけ。 公開リポジトリなので誰でも read は持つが、それでは足りない。 自分が出した PR は、自分で承認できない。 レビュアーの構成は GitHubUsage.md 2 節。

コーディング規約は CODING.md、領域ごとの事情は ANALYSIS.md に従う

規約は全領域に共通、分析は領域ごとに分かれている。

内容 読む文書
コーディング規約（全領域共通） CODING.md
設定ファイルの扱い（全領域共通） CONFIGURATION.md
root/programs/CS/Frameworks/ の分析 Frameworks/ANALYSIS.md
root/programs/CS/Samples/ の分析 Samples/ANALYSIS.md
root/programs/CS/Samples4NetCore/ の分析 Samples4NetCore/ANALYSIS.md

上の 3 つは俯瞰であり、詳細はアセンブリ・サンプルごとの下位の ANALYSIS.md にある（#613）。 下位の文書は、各文書の冒頭にある案内表から辿る。

設定ファイルに「仕組み」を書き足したくなったら、CONFIGURATION.md に書く。 設定ファイルは 86 個あり、一部にだけ詳しい説明があると、 書かれていないファイルを「該当しない」と誤読させる。 値の隣に書くのは「そのキーが何か」までにする（分担は同書 0 節）。

コードを変更する前に、CODING.md と、 作業対象を所管する ANALYSIS.md の両方を読むこと。

CODING.md には、ファイル ヘッダの書式と更新者名、新規ファイルにおける Copyright ブロックの扱い、ArgumentException 系の引数の順、.bat / .ps1 の 文字コードなど、エージェントが見落としやすい指定が含まれる。

各 ANALYSIS.md は、その領域におけるアーキテクチャ・ビルド手順・条件コンパイル・ 既知の落とし穴の一次情報である。末尾の 「エージェント向け作業チェックリスト」には着手前に目を通すこと。

規約の実体はこのファイル（AGENTS.md）には書かない。二重管理になり、 どちらが正なのか分からなくなる。

ビルド・テスト・リリースの検証は、専用の文書に従う

検証の手順そのものは、人もエージェントも同じである。 入口は root/Readme.ja.md の「ビルド後の検証」で、 3 本のスクリプト（ビルド → 単体テスト → 疎通）と、その一次情報 （BUILDING.md / TESTING.md / SMOKETEST.md、リリース時の作業全体は RELEASE.md）は、 そこから辿れる。本節は、その上で残るエージェント固有の判断だけを扱う。

手順だけを引くなら CHEATSHEET.md 1 節。 引数（-IgnoreErrors / -Only / -List / -Lang）・合格の目安・ 実行順（固定。1 のクリーンとアセンブリ配置が 2・3 の前提）は、そこが一次情報である。

本書にコマンドは書かない。転記すると、両方を直さないかぎりズレる。

2_RunAllTests.ps1 はワーキング ツリーの Result*.txt を書き換える（従来のバッチ運用と同じ）。 コミットの要否は人が判断するため、エージェントは差分を報告するに留める。 -Only で絞れば、書き換わるのも絞った分だけになる。

回す範囲は、依存関係で決める（#576）

全部回すのは「安全」ではない。遅いだけのことがある。

0_RunAll.ps1 は 3 本をまとめて回す利用者向けの入口であり、 必要な 1 本だけを選ぶ、という判断が入らない。 エージェントは3 本を個別に実行することを検討する。

ツールと個別サンプルは依存の末端で、そこを変えても基盤も他のサンプルも変わらない。 2_RunAllTests.ps1 の対象はフレームワークのテストだけで、 ツールやサンプルを変えても動かない。回す理由が無い。

どこまで回すかは CHEATSHEET.md 1 節の対応表で決める。

その判断は SelectTargets.ps1 で機械的に行える（#610）。 検証の済んだコミットからの差分（未コミット・未追跡を含む）を読み、 回す対象を 1 / 2 / 3 ごとに割り出す。まずこれを回し、結果を見てから実行する。 「手で確かめるもの」が出たら、回せていないものとして報告する。 使い方は同じく CHEATSHEET.md 1 節。

通しを回すのは次の場合。

  • 基盤（Infrastructure/）に触れたとき
  • リリース前（RELEASE.md）
  • 絞り込みで妙なエラーが出たとき（再現するかを見る。制約による誤検知が実際にある）

判断に迷ったら通しでよい。 ただし迷っていないのに通すのは、ただの浪費である。

コミットの段階で、回す量を変える（#610）

施主のコミットは段階を表す。 fixing #N (phX) は途中、fixed #N は完了。 途中で毎回すべてを回す必要は無い。完了の前に、後回しにした分も含めて回せばよい。

段階 いつ 回すもの
編集中 直しては確かめる反復 変えたテストだけを直接回す（秒〜数十秒）
fixing 途中のコミットの前 SelectTargets.ps1 -Stage fixing -Run。重いものは後回しになる
fixed 完了のコミットの前 SelectTargets.ps1 -Run（既定の fixed）。後回しの分も含めて回す。通れば記録が進む
リリース RELEASE.md 全部（VB・クロス DB・GUI の手作業を含む）

fixing で後回しにするもの（SelectTargets.ps1 が一覧に出す）。

  • DB を使う対象（Northwind に接続する単体テストと疎通）
  • 基盤に触れたときの、基盤以外のビルドと疎通の通し。 単体テストは基盤の DLL だけを見るので、ビルドは基盤だけで回せる

リソースが要るものは、触れたときだけ回す。 fixed でも、関係が無ければ回さない。

リソース 回すとき
クロス DB（Oracle / MySQL / PostgreSQL のコンテナ） Dam・SQL の生成（Public/Db、Dam*）に触れた fixed と、リリース
VB 側（-Lang VB） VB のソース、または VB が取り込む基盤に触れた fixed と、リリース
Linux（-Linux。net10.0 の出力を Linux のコンテナで回す） Public・Public.Security に触れた fixed と、リリース（SelectTargets.ps1 が付ける。#632）
管理者権限（イベント ログの NUnit） CustomEventLog に触れたとき。手元が管理者でなければ、回せていないと報告する

コンテナやサービスは勝手に起動しない（下の「前提となるサービスや DB」と同じ）。必要なら施主に確認する。

DB のコンテナは、LocalServicesOnDocker の CHEATSHEET.md に従って扱う。 メモリを節約しないと、最悪の場合、コンテナがシステムごとハングさせる。 必須でないものを同時に複数起動せず、1 つずつ起動して測り、終わったら止める。 手順の要点は TESTING.md の冒頭。

次のコミットがどちらの段階か分からなければ、施主に確かめるか、fixed として回す。 報告には、どの段階で回したかと、後回しにしたものを書く。 後回しのまま「検証済み」と書かない。

コマンドと表示の読み方は CHEATSHEET.md 1 節。

簡易な変更なら、毎回は回さないという選択もある

変更が実行されるコードに届いていないなら、通しを回しても何も分からない。 文書のみ、コメントのみ、表示文言のみといった変更がこれに当たる。 検証は目的ではなく、壊していないことを確かめる手段である。

変更 目安
文書（.md）のみ 回さなくてよい
コメント・表示文言のみ 変えたスクリプトを -Only で 1 件だけ回し、表示を見る
ツール・個別サンプル その対象だけ（依存の末端なので、他は変わらない）
基盤（Infrastructure/） 通し（上のとおり）

ただし、.ps1 を変えたなら、表示だけの変更でも実行すること。 構文エラーは読んでも分からず、5.1 と 7 で振る舞いが違う （CODING.md 5 節）。

回さなかったなら、そう報告する。 「検証済み」と書かない。 回していないのに回したように読める報告が、一番危い。 検収する人は、何が確かめられていないかを知っている必要がある。

CI（GitHub Actions）はこれとは別である。 push すれば回るので、手元で省いた分はそこで拾われる。 ただし結果が出るのはコミットの後なので、 実行されるコードを変えたなら、手元で見てから渡すこと。

上記の既定は C# 側である。VB 側に手を入れたときは -Lang で回す。 理由と対象は BUILDING.md 10 節・ SMOKETEST.md 10 節。

.ps1 は Windows PowerShell 5.1 と PowerShell 7 の両方で動くこと。 エージェントの実行環境は 7 だが、利用者は 5.1（powershell.exe）で実行するため、 7 だけで確認すると 5.1 で落ちる。変更したら 5.1 でも実行して確かめること。

規約の実体は CODING.md の **5 節「ps1 の文字コードと PowerShell 5.1 / 7 の両対応」**にある。

前提となるサービスや DB の状態が足りない場合は、勝手に変えず、対処方法とともに報告する。

サンプルを実装するときは、スキル リポジトリのスキルを使う（#577）

サンプルは「フレームワークを使うアプリ」である。 その書き方は本体の規約とは別に、専用のスキルとしてまとめられている。

https://github.com/OpenTouryoProject/OpenTouryoCodingAgentAssets

AGENTS.md に書くだけでは使えない。 Claude Code は .claude/skills/<名前>/SKILL.md を探すため、実体が要る。

cd root\programs
.\GetAgentSkills.ps1              # main から取得して .claude/skills へ配置
.\GetAgentSkills.ps1 -List        # 何が対象になるかだけ見る

.claude/skills/ は .gitignore の対象である。 ここに在るのは複製で、本体は向こうのリポジトリにある。 コミットすると、向こうが更新されたときに古くなり、どちらが正か分からなくなる。 使う前に取得する。

向こうの install.ps1 は使わない

あちらにも導入スクリプトがあるが、フレームワークの利用者（アプリ開発）向けで、 導入先の AGENTS.md と CLAUDE.md も生成する。 本書は手で書いたものなので、スキルだけを取りに行く。

既定で除外しているもの

除外 理由
opentouryo-project-setup*（6 件） アプリの新規構築手順。本体の開発では使わない
opentouryo-project-policy プロジェクト方針は本書（AGENTS.md）が正
opentouryo-project-transform 既存資産の移行。本体側では別の話
opentouryo-comment-convention コメント規約は CODING.md が正
opentouryo-base2-customize 利用者による基底クラスの改造。本体側では別の話

除外を増やしたら、取得し直せば取り残しも消える。 前回配置したものが除外に回った場合、GetAgentSkills.ps1 が削除する （消すのは向こうに在るスキル名だけで、無関係なものは触らない）。

規約が競合したら、本体の文書が優先である。 スキルはアプリ開発を前提に書かれているため、 CODING.md や各 ANALYSIS.md と食い違うことがある。

付属ツールを CLI で使うときは、各ツールの README に従う

エージェントから実行できる（非対話の）ツールには README を置く。

ツール 読む文書
DaoGen_Tool（Ｄ層自動生成ツール／墨壺） README.md
DeployZipPackWithHTTP（ZIP パッケージの HTTP 配布） README.md

引数の一覧は README に書かない。 ツールの /HELP が一次情報であり、 書き写すと二重管理になる。README には README にしか書けないこと （実行ファイルの場所、ヘルプの出し方、踏みやすい罠、前提）を置く。

  • 引数を組み立てる前に、まず /HELP を実行する
  • 終了コードだけで判断せず、生成物の存在も確認する （パス区切りを誤ると、成功（0）を返しつつ別の場所に出力される）