From a885082683271ecd860f021d4328090b739a830c Mon Sep 17 00:00:00 2001 From: Tokuhiro Matsuno Date: Fri, 9 Oct 2026 18:57:00 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=E3=83=AC=E3=83=93=E3=83=A5=E3=83=BC?= =?UTF-8?q?=E6=8C=87=E6=91=98=E3=81=AE=E5=86=8D=E7=99=BA=E9=98=B2=E6=AD=A2?= =?UTF-8?q?=E6=96=B9=E9=87=9D=E3=82=92=20AGENTS.md=20=E3=81=AB=E8=BF=BD?= =?UTF-8?q?=E5=8A=A0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Tokuhiro Matsuno --- AGENTS.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index fae4c8d..d6e2439 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,16 +11,20 @@ - 依頼された内容に変更を絞り、依頼で明示されていない限り既存の動作を維持してください。 - ユーザーから見える動作やコマンドを変更する場合は、関連するドキュメントも更新してください。 +- ヘルプと使用例は、実際の位置引数、生成されるフラグ、JSON 専用フィールドと照合してください。入力間の制約を説明する場合は、CLI または呼び出す SDK で制約が検証されることも確認してください。 - コマンド引数・フラグには、秘密情報を含めないでください。認証情報（API キー、トークン、パスワード、秘密鍵など）は引数として受け取らず、既存の認証設定や認証機構を使ってください。API リクエストに秘密情報が必要な場合も、`--password VALUE` や `--request='{"password":"VALUE"}'` のように秘密情報の値を引数として渡させず、秘密情報を含むリクエストを保護したファイルまたは標準入力から読み込んでください。秘密情報の実値をヘルプ、使用例、エラーメッセージに含めないでください。 - JSON や PEM などの内容を値として受け取る引数で、インライン指定に加えてファイルからの読み込みをサポートする場合は、`@path` 形式を使います（例: `--request @request.json`）。標準入力からの読み込みもサポートする場合は `-` を使います。`@path` と `-` はその引数が明示的に対応する場合にだけ使えるものとし、対応形式を `--help` に記載してください。 - コマンドの主な対象を表す値には位置引数を使い、追加の条件や設定値には名前付きフラグを使ってください。API リクエストを受け取る操作のフラグ化は、独立した単純なスカラー値で有効なリクエストを表現できる場合に限ります。ただし IaaS API のトップレベル `Tags` 配列は、個別フラグ入力に対応する操作で `--tags` によるカンマ区切り指定をサポートします。その他の複雑な値や配列、秘密情報は JSON など適切な入力経路に残してください。`--request` と個別フラグを設ける場合は相互排他とし、暗黙にマージしないでください。詳細は [ADR 0007](docs/adr/0007-api-request-input.md) と [ADR 0035](docs/adr/0035-iaas-tags-flag.md) を参照してください。 - サービス／API ドメインの開発進捗に変更があった場合は、実装状況と未対応作業を `PLAN.md` に反映してください。 +- `PLAN.md` には新しいリソースも追加し、実装した操作の範囲、ライブ E2E、チュートリアルの対応状況を区別してください。コマンドの入口があるだけで全操作を実装済みとして扱わないでください。 - サービス仕様の調査では公式マニュアルと対象 SDK のドキュメントを根拠にします。調査での情報源の扱いと利用者向け文書の語り口は分け、根拠が確認できた仕様は直接説明して参照リンクを添えてください。不確かな仕様は推測せず、確認できるまで記載しないでください。 - CLI のヘルプやエラーメッセージでは、利用者に SDK の実装詳細を意識させないでください。フィールドの対応先を示す必要がある場合は「API のフィールド」として説明し、SDK 内部の型や実装レイヤーを利用者向け文言に出さないでください。 - `SKILL.md` は日本語で記述してください。メタデータの識別子、コマンド、コード例など、変更すると機能や意味が変わる箇所はそのままにしてください。 - 日本語の説明文は文書内で文体を統一し、原則として「です・ます」調にしてください。箇条書きも本文と同じ文体にし、ルールに合わせるためだけに不自然な言い換えをしないでください。 +- GitHub Issue のタイトルと本文は日本語で記述してください。識別子、コマンド、コード、製品名などは、意味が変わらないよう元の表記を維持してください。 - Markdown ファイルを追加・変更した場合は、コミット前に `make lint-text` を実行してください。妥当な技術用語や製品表現への誤検出は、意味を損なう修正をせず、必要に応じて対象ルールを設定で除外してください。 - 開発時の意思決定は `docs/adr/` に ADR として記録してください。作成時は [`docs/adr/template.md`](docs/adr/template.md) を使い、連番とタイトルを付けてください。 +- ADR の作成前に既存の番号を確認し、重複しない番号を使ってください。番号やファイル名を変更する場合は、文書内の番号と参照リンクも更新してください。 - 設計内容は design doc として記録してください。 - 新規作成するファイルの名前に `config` が含まれる場合は、`c0nfig` という綴りにしてください（例: `internal/cli/c0nfig.go`、`docs/manual/c0nfig.md`、`test/e2e/c0nfig/`）。E2E evidence のステップ名など、ツールがファイル名を生成する元になる文字列も `c0nfig` にしてください。 - 現在のテンプレート由来のモジュール名、バイナリ名、ビルド設定を製品の要件とみなさないでください。依頼に必要な場合に限り変更してください。 @@ -29,11 +33,20 @@ - API コマンド生成器は、IaaS 用の `cmd/apigen-iaas` / `generate-iaas-api` と、Ogen 系 API 用の `cmd/apigen-api` / `generate-api` を使います。IaaS は Ogen 系 API と生成対象の形が異なるため専用入口を維持し、Ogen 系 API はサービスごとに入口を増やさず共通入口を使います。 - 生成器の設定解析・検証・共有可能なコード生成機構は `internal/apigen` に配置します。IaaS 固有の処理は `request_validator` などで明示し、全ゾーン検索のためのゾーン列挙や結果集約は生成器に追加しません。共通化できない処理を無理に共通パッケージへ集めず、生成処理の差が大きくなった場合は IaaS と Ogen 系 API の実装を個別に保守できる境界を検討します。 +- 生成器では、コマンド、API、factory、Runtime、操作ごとの型を含む生成型名全体の衝突を設定検証で拒否してください。検証のテストに加え、再生成したコードのビルドと設定との一致を確認してください。 - 生成された IaaS リソースコマンドは `internal/iaas/api/` に配置します。たとえば Switch の生成コマンドは `internal/iaas/switchapi/`、Switch 固有の検証は `internal/iaas/switch/`、複数リソースで共有するクライアントとゾーン名の検証は `internal/iaas/client/` と `internal/iaas/zones/` に配置します。 - Ogen 系の非 IaaS API コマンドは `internal/api/` に配置します。SimpleMQ のように生成コマンドとドメイン固有の手書きハンドラーが混在する場合は、両方を同じドメインパッケージに置き、公開する Commands 型、API interface、factory、Runtime を通じて接続します。生成コードは設定から再生成し、直接編集しません。 - `cmd/skr` の `package main` は `internal/cli` の CLI 実行関数を呼び出すエントリーポイントです。CLI の登録と Runtime callback／SDK factory の接続は `internal/cli` が担当し、生成パッケージから CLI の非公開処理へ依存させません。 - ドメイン固有のコマンド実装と単体テストはドメインパッケージに置きます。CLI のコマンド構成、接続処理と CLI 全体の登録・実行を検証するテストは `internal/cli` に置きます。 - 個別パッケージの単体テストは、検証対象のパッケージと同じディレクトリに配置します。 +- 手書きの入力処理やリクエスト検証には、同じパッケージで正常系とエラー系の単体テストを追加してください。CLI 全体のテストだけで代替せず、秘密情報のインライン入力拒否と非表示、ファイルや標準入力の読み込み失敗、型違い、必須項目、相互排他も対象にしてください。 + +## 入力処理と通信の検証 + +- JSON やファイルの読み込みを追加する前に既存処理を確認し、共有可能な処理は再利用してください。対応する入力形式や秘密情報の制約が異なる処理を、挙動を変えてまで共通化しないでください。 +- JSON 入力では、未知のフィールドや末尾の余分なデータの扱いを確認してください。独自の JSON デコードを行う型や入力補完も含めて検証し、ドメイン間で扱いを変える場合は理由を設計文書に記録してください。 +- 通信のタイムアウトとキャンセルは、CLI だけでなく SDK の既定値、プロファイル、環境変数も確認してください。変更時はリトライとレスポンス本文の読み込みを含む適用範囲を明確にし、エラーが利用者へ返ることを検証してください。 +- API モックのエラーは、SDK が判定するエラー型とステータスに合わせてください。対象が存在しない場合など、エラーの分類で変わる動作も検証してください。 ## 検証