schedule-system

Imported from yuya-dev-dev/schedule-system (AGENTS.md). Install upstream with npx skills add yuya-dev-dev/schedule-system. Copyright stays with the author.

AGENTS.md

1. 適用範囲

このファイルの指示は、このリポジトリ全体に適用する。

現在のタスクについてユーザーから明示的な指示がある場合は、その指示を本ファイルより優先する。

このファイルは恒久的な作業ルールを定義する。現在の進捗、次にやること、未完了タスクはREADMEと開発ロードマップへ分離する。

2. 基本方針

このリポジトリでは、正確性を維持しながら、変更範囲、調査範囲、テスト範囲、GitHub操作を必要最小限に抑える。

• 指示された目的に直接関係する変更だけを行う
• 既存の設計、命名、ディレクトリ構成、コーディング規約に従う
• 差分を小さく、目的を明確に保つ
• 目的と無関係な修正、整理、リファクタリングを行わない
• 将来必要になる可能性だけを理由に抽象化や機能追加を行わない
• タスク判断に必要なファイルから読む
• 理由なくリポジトリ全体を繰り返し調査しない
• 一度確認した内容を理由なく再調査しない
• 軽微な変更で外部レビューエージェントを使用しない
• 実装、テスト、GitHub操作を必要以上に繰り返さない

3. 作業開始時の確認

作業開始時は必ず次を確認する。

1. pwd
2. git status --short --branch
3. 現在のブランチ
4. 直近のユーザー依頼
5. 変更対象の直接関連ファイル

作業フォルダは、ユーザーがVS Codeで開いているクローンを正とする。現在の主作業場所は C:\Users\ユーザー\OneDrive\ドキュメント\scheduleシステム である。

Codexの実行環境上の作業フォルダと、ユーザーがVS Codeで開いているリポジトリがズレていないか注意する。必要に応じて git remote -v も確認し、対象リポジトリが yuya-dev-dev/schedule-system であることを確認する。

古い作業フォルダや別クローンを編集しない。作業場所が不明な場合は、実装前に停止して確認する。

4. プロジェクト固有の制約

このプロジェクトは、配送・設置案件のスケジュール管理Webアプリケーションである。主な画面は、月間スケジュール一覧と案件入力フォームである。

技術構成は、Java / Spring Boot / Thymeleaf / DBを中心とする。ローカル開発ではH2、本番・クラウド検証ではPostgreSQLを使用する可能性がある。H2とPostgreSQLの挙動差、特に制約、排他制御、マイグレーション差分に注意する。

• 実在する顧客、従業員、会社、住所、電話番号、メールアドレスなどを追加しない
• テストデータ、サンプルデータ、初期データ、スクリーンショットには架空の情報だけを使用する
• 既存のアクセス制御仕様を、明示的な依頼なしに変更しない
• 新たなログイン、ユーザー管理、権限管理を、明示的な依頼なしに追加しない
• 依頼と無関係な既存機能の動作を変更しない
• 新しい本番用ライブラリや依存関係を、ユーザーの承認なしに追加または更新しない
• 大規模な設計変更は、ユーザーの承認なしに行わない
• Render、Neon、cloud profile、Basic認証、Docker、Docker Compose、デプロイ設定の変更は慎重に扱う
• 本番環境、本番DB、本番認証情報には、ユーザーの明示許可なしに接続しない
• 本番データを直接変更する操作は原則行わない
• Render、Neon、環境変数、DB接続文字列、パスワード、秘密値を会話、ログ、スクリーンショット、ドキュメントへ不用意に出さない
• Renderへ反映した後は、必要に応じてデプロイ対象commitとGitHubのmain最新commitが一致しているか確認する
• 画面変更ではPC表示だけでなく、必要に応じてiPhone Safariでの確認観点も提示する

5. Gitとブランチの安全規則

作業開始前に、現在のブランチと作業ツリーの状態を確認する。

• コード、DB、認証、クラウド設定、デプロイ挙動に影響する変更は、mainへ直接コミットしない
• コード、DB、認証、クラウド設定、デプロイ挙動に影響する変更は、mainへ直接pushしない
• ドキュメントだけの変更は、ユーザー判断でPRを作らずmainへ直接反映してよい
• 現在のブランチがmainの場合は、変更前に作業用ブランチを作成する
• タスク用ブランチが指定されている場合は、そのブランチを使用する
• 強制pushを行わない
• コミット履歴を書き換えない
• ユーザーや別のエージェントが行った可能性のある変更を破棄しない
• git reset --hardなどの破壊的なコマンドを使用しない
• 現在のタスクに関係するファイルだけをステージング対象として扱う
• PDF、スクリーンショット、一時ファイル、ローカル生成物は、ユーザーが明示しない限りgit addしない

1つのPRには、同じ目的に属する変更だけを含める。同じ機能に関連する複数の軽微な変更は、1つの作業ブランチと1つのPRへまとめてよい。目的の異なる変更は混在させない。

6. 実装前の確認

実装前には、必要最小限の範囲だけを調査する。

1. ユーザーが指定したファイルを確認する
2. 変更対象の直接的な依存先を確認する
3. 既存の実装方法と近隣のテストを確認する
4. 必要に応じて関連ドキュメントを確認する
5. 変更予定の範囲を特定する

必要性が判明するまでは、調査範囲をリポジトリ全体へ広げない。

要件が曖昧で、実装によって動作やデータ構造が大きく変わる場合は、推測で実装せずユーザーへ確認する。

7. 実装方針

• 最小差分で実装する
• 既存コードや既存パターンを可能な限り再利用する
• 指示されていない機能を追加しない
• 目的と無関係な命名変更を行わない
• 目的と無関係なコード整形を行わない
• 目的と無関係なファイル移動を行わない
• テストのためだけに大規模なリファクタリングを行わない
• 同じタスク内の関連変更は、細かな編集ごとに中断せずまとめて実装する
• ドキュメントは、今回の変更によって記載内容が実際に変わる場合のみ更新する

実装完了後は次を確認する。

• 変更したファイルの差分
• 目的と無関係なファイルが変更されていないこと
• 依頼された機能以外へ変更が広がっていないこと
• テストコードが変更内容と一致していること

8. テストの役割分担

原則として、Codexはテストコードを作成または修正し、軽微な変更ではユーザーがテストコマンドを実行する。

Codexは、ユーザーから明示的に依頼された場合、または動作確認に不可欠な場合に限り、対象限定テストや必要最小限の確認を実行してよい。

ただし、Docker、E2E、外部サービス接続、本番環境接続を伴う操作は、ユーザーから明示依頼がない限り実行しない。

Codexが担当する作業：

• 変更に必要なテストコードを追加または修正する
• 既存の近隣テストを優先して利用する
• 変更内容を確認できる最小限のテストだけを追加する
• ユーザーが実行すべき正確なコマンドを提示する
• テストの種類と確認できる範囲を説明する
• DBや外部サービスへ接続する可能性がある場合は事前に警告する

ユーザーが担当する作業：

• テストコマンドを実行する
• 成功または失敗を確認する
• 必要な場合だけ失敗結果をCodexへ報告する
• 手動で画面や操作を確認する

9. テスト範囲

軽微で局所的な変更

変更直後は、変更箇所に直接対応する対象限定テストを提示する。

対象限定テストとは、全テストを実行せず、今回変更した機能に直接関係するテストクラスまたはテストメソッドだけを実行することを指す。

テストクラスを限定する例：

.\mvnw.cmd "-Dtest=MonthScheduleServiceTest" test

テストメソッドを限定する例：

.\mvnw.cmd "-Dtest=ScheduleRequestAutosaveServiceTest#shouldSaveDraftWhenRequiredFieldsAreMissing" test

対象限定テストに成功しても、システム全体に影響がないと断定してはならない。

同じ目的の実装がまとまった時点

次の場合は、Maven testフェーズの実行をユーザーへ提案する。

• 同じ目的の複数の変更が完了した
• 1つの機能が完成した
• PRを作成する直前
• 共通コードを変更した
• 複数の機能から利用される処理を変更した

Maven testフェーズの基本コマンド：

.\mvnw.cmd test

より広い検証が必要な変更

以下を変更した場合は、対象限定テストだけでは不十分な可能性があるため、必要な統合テストまたは起動確認を提案する。

• DBスキーマ
• マイグレーション
• Repository
• 複数のService間の連携
• Springの設定
• 依存性注入
• ルーティング
• 共通例外処理
• 認証または認可
• 依存関係のバージョン
• Dockerまたはデプロイ設定
• 複数モジュールにまたがる変更

verifyなどのコマンドを提示する前に、pom.xmlを確認し、そのコマンドで実際にどのテストが実行されるかを確認する。

設定を確認せず、すべての変更に対して一律にclean testやclean verifyを提案しない。

手動確認

画面またはユーザー操作に関係する変更では、必要最小限の手動確認手順も提示する。

例：

1. アプリケーションを起動する
2. 変更した画面を開く
3. 正常な入力で操作する
4. 必要に応じて不正な入力も確認する
5. 保存結果または表示結果を確認する

10. 実装完了後の停止条件

実装と必要なテストコードの作成が完了したら、Codexは次を報告して停止する。

軽微な変更では、以下だけでよい。

1. 変更したファイル
2. 実装内容の要約
3. 実施した確認
4. ユーザーが次に実行すべきコマンド

リスクがある変更では、必要に応じて次も報告する。

• 最初に実行すべき対象限定テスト
• Maven testフェーズが必要かどうか
• 必要な手動確認
• テストによって確認できない範囲
• 既知の注意点または仮定

Codexは基本的に差分チェックとローカル状態確認までで停止し、commit、push、PR作成、マージはユーザーが行う。ユーザーが明示的に代理実行を依頼した場合だけ、Codexがcommit、push、PR作成を行ってよい。

11. テスト失敗時の対応

ユーザー実行のテスト失敗は、報告されたコマンドとログをもとに調査する。

調査の順序：

1. 実行されたコマンドを確認する
2. 最初に失敗した関連テストを確認する
3. 主要な例外と最初の原因箇所を確認する
4. 必要に応じてtarget/surefire-reports内の該当レポートだけを確認する
5. 今回の変更が原因かを判断する
6. 最小差分で修正する
7. ユーザーへ再実行コマンドを提示する

Codexが実装中に明らかな構文ミス、コンパイル不整合、設定不整合を発見した場合は、その場で最小差分で修正してよい。

以下を行わない。

• 最初からログ全体を読み込む
• 無関係な失敗を調査する
• 同じログを何度も読み直す
• 原因が不明なまま大規模な修正を行う
• 同じ失敗に対して無制限にテストを繰り返す

再実行は原則1回までとする。2回修正しても解決しない場合は作業を停止し、次を報告する。

• 確認した内容
• 実施した修正
• 現時点で不明な点
• 次に行うべき最小限の調査

12. コマンド出力とログの制限

大量の出力を会話コンテキストへ取り込まない。

• git statusは可能な限り簡潔な形式を使用する
• 最初にgit diff --statで変更規模を確認する
• 関連ファイルの差分だけを読む
• 全ログではなく、エラー周辺や末尾の必要な部分だけを読む
• 不明なコマンドの大量出力をそのまま表示しない
• 必要なら完全なログをローカルファイルへ保存し、該当箇所だけを確認する
• 同じ大きな出力を繰り返し会話へ掲載しない

コマンドが5分以上終了しない場合は、理由なく待ち続けたり再実行したりせず、停止して状況を報告する。

13. Commit、push、PR作成、マージ

commit、push、PR作成、マージは原則としてユーザーが行う。

Codexは、ブランチ作成、実装、差分確認、ローカル状態確認、ユーザーが実行すべきGitコマンド提示までを担当する。

変更内容は、ユーザーがVS Codeで開いているクローン上で確認し、ユーザーがGitHubのmainへ反映する。Codex側の古い作業フォルダだけに変更を残さない。

Codexがcommit、push、PR作成を代理実行してよいのは、ユーザーが明示的に依頼した場合だけである。代理実行する場合も、PR作成までを基本とし、マージは行わない。

ドキュメントだけの変更は、ユーザー判断でPRを作らずmainへ直接commit/pushしてよい。コード、DB、認証、クラウド設定、デプロイ挙動に影響する変更はPRを作成する。

Codexがユーザーへ提示する基本手順：

1. 現在のブランチを確認する
2. 差分を確認する
3. タスクに関係するファイルだけをステージングする
4. 変更内容を具体的に表すコミットを作成する
5. 作業ブランチをpushする
6. main向けのPRを作成する
7. ユーザーがPRを確認してマージする

PR本文を作る場合は簡潔にし、次だけを記載する。

• 変更目的
• 主な変更内容
• 実行した、またはユーザーが実行すべきテスト
• テスト結果
• 必要な注意点

明示依頼がない限り、PR作成後に次を行わない。

• CIの完了待ち
• CIの定期的な確認
• CIログの分析
• 追加のAIコードレビュー
• 不要なコメントやレビュー依頼
• 自動マージ
• 手動マージ

14. Codexサブエージェントレビューの扱い

レビュー補助が必要な場合は、Codexのサブエージェントをレビュー担当として使用する方針とする。ただし、サブエージェントは実装担当ではなく、計画、差分、テスト観点、リスクのレビュー補助として扱う。

サブエージェントは、明示的に厳格レビューを指示しないと指摘が緩くなる可能性がある。利用時は、称賛や総評を先に求めず、重大度付きの欠陥指摘、根拠、修正案、テスト観点を固定フォーマットで出力させる。

サブエージェントを使用する場合の原則：

• 軽微な変更では使用しない
• 使用前にレビュー目的と対象範囲を明確にする
• サブエージェントにはこのAGENTS.mdを読ませる
• サブエージェントには対象差分、または実装前レビューなら実装方針と関連ファイルを読ませる
• 現在の進捗や次工程がレビュー判断に必要な場合だけ、READMEまたは開発ロードマップの必要部分をレビュー依頼本文へ抜粋する
• サブエージェントには厳格レビュー用プロンプトを使い、出力形式を固定する
• サブエージェントにcommit、push、PR作成、マージを依頼しない
• サブエージェントに本番環境、本番DB、本番認証情報へ接続させない
• サブエージェントに秘密値、環境変数、DB接続文字列、実在する個人情報を渡さない
• サブエージェントの指摘は採用前にCodexが妥当性を判断する
• 採用しない指摘がある場合は、理由を簡潔に説明する

サブエージェントのレビューが有効な場面：

• 画面UIやUXの変更範囲が広い場合
• DB、認証、デプロイ、クラウド設定に関係する場合
• 複数ファイルへ影響する実装の場合
• テスト観点の抜け漏れを確認したい場合
• PR前に第三者視点のリスク確認をしたい場合

サブエージェントへ渡す厳格レビュー用プロンプトの基本形：

あなたは schedule-system の厳格なコードレビュー担当です。
実装、ファイル編集、commit、push、PR作成、マージ、外部環境接続、本番DB接続は行わないでください。
称賛、励まし、抽象的な総評を先に書かないでください。
問題がない場合だけ「重大な指摘なし」と明記してください。

以下を前提に、レビュー対象を厳しく確認してください。

- AGENTS.md の作業ルール
- レビュー依頼本文に含まれる現在状況
- 既存仕様との整合性
- データ破損、上書き、削除、認証、DB、クラウド設定のリスク
- テスト不足
- 不要な差分

出力形式は必ず次に従ってください。

## Findings

### [P0] タイトル
- 対象: ファイル名、関数名、画面名、または該当箇所
- 問題: 何が壊れるか
- 根拠: なぜそう判断できるか
- 修正案: 最小修正案
- 必要テスト: 追加または実行すべきテスト

### [P1] タイトル
同上

## Questions
- 実装前または採用前にユーザーへ確認すべきこと

## Non-blocking
- 任意改善。今回対応しなくてよいもの

## Verdict
- BLOCK: mainへ入れる前に修正必須
- CONDITIONAL: 条件付きで可
- PASS: 重大な指摘なし

レビュー対象:
<ここに計画、差分、ファイル抜粋、スクリーンショット説明を貼る>

15. 禁止事項

明示的な依頼がない限り、以下を行わない。

• リポジトリ全体の大規模なリファクタリング
• 目的と無関係な依存関係の追加または更新
• 目的と無関係なファイルの編集
• コードスタイルの一括変更
• ドキュメントの全面書き換え
• 不要なIssueの作成または更新
• 軽微な変更ごとの全テスト実行
• 軽微な変更ごとの統合テストまたはE2Eテスト
• カバレッジ測定
• パフォーマンス測定
• 同じコマンドの不必要な再実行
• PR作成後の継続的な監視
• 依頼範囲と無関係なセキュリティ機能の追加

16. 依頼範囲外の重大な問題

依頼範囲外に、明らかなバグ、情報漏えい、データ破損、重大なセキュリティ問題を発見した場合は、勝手に修正しない。

次を簡潔に報告し、ユーザーの承認を待つ。

• 問題がある場所
• 想定される影響
• 今回の変更との関係
• 最小限の修正案