ワークフローを動かす大きなPythonモノレポを、AIに壊さず直させる

## 直す前に、担当のパッケージとその決まりを調べる 文章ではプロジェクトの正式なドメイン用語を使う。リテラル識別子、コマンド、パス、設定キー、互換性のための名称はコードが求めるとおり正確に保ち、表記統一だけを目的に書き換えない。 編集前に次を行う。 - 担当パッケージ、そのローカル指示、最寄りのアーキテクチャまたはテストガイドを特定する。 - ホストのツールを直接起動せず、プロジェクト管理下の開発・テスト用ラッパーを使う。 - 文書化された一度限りのセットアップで、リポジトリのフックまたはコマンド用補助機構を導入する。 - 一時的な補助スクリプトは指定されたマウント済み開発領域だけに置き、タスク完了時に取り除く。 - 実際に変更したファイルとパッケージに応じて検査を選ぶ。 生成された依存関係ロックなどの成果物は公式ジェネレーターの出力として扱い、手作業で編集するソースにはしない。 ## スケジューラーにコードを動かさせず、ワーカーにデータベースを直接触らせない オーケストレーションコードを変更する前にデータフローを理解する。 1. 作成者は公開SDKを通じてワークフローを定義する。 2. 分離された処理系が定義を解析し、直列化したワークフローデータを永続化する。 3. スケジューラーは直列化データを読み、作成者が提供したワークフローコードを実行してはならない。 4. ワーカーは対応SDKまたはAPIを通じてタスクを実行し、メタデータベースへ直接アクセスしてはならない。 5. APIサービスはユーザーインターフェースおよびクライアントと永続状態のやり取りを仲介する。 6. イベント起動サービスはスケジューラーやワーカーとは別に動作する。 コンポーネント間では有効期間が短く、範囲を狭く限定した資格情報を使う。データベースへの直接アクセスを抑止するソフトウェア検査は有用な安全柵だが、意図的な悪意あるコードに対するセキュリティ境界ではない。 修正を提案する前に、疑わしいセキュリティ問題を分類する。 - 文書化された信頼モデルへの悪用可能な違反は脆弱性である。 - 信頼モデルの範囲外だとすでに宣言された動作は既知の制限である。 - 破られた保証を修復しない、より安全な配備方法の選択は堅牢化の指針である。 実際のリスクに重大度と修復方法を合わせるため、この3分類を混同しない。 ## 依存関係は、それをインポートするパッケージに置く モノレポを一つの未分化なパッケージではなく、関連する配布物の集合として扱う。中核オーケストレーション、公開SDK、プロバイダー連携、コマンドラインツール、配備チャート、開発ツール、スクリプトでは、リリース周期と依存関係の規則が異なる場合がある。 共有ライブラリでは次を守る。 - APIを小さく独立した状態に保つ。 - 専用のソースツリー、テスト、設定、宣言済み依存関係を持たせる。 - コードを複製せず、リポジトリが対応するワークスペースリンクを使う。 - ライブラリ本体と、直接影響を受けるすべての利用側をテストする。 依存関係は、それをインポートする配布物に置く。変更がパッケージ境界を越える場合は、マニフェストを変更する前にインポート方向とリリースの所有者を確認する。 対応ワークフローでロックファイルを再生成し、得られた依存関係の差分に無関係な変動がないか確認する。 ## 読みやすいPythonコードを書き、1回の変更を小さく保つ 変更が小さいうちに、変更した各Pythonファイルを整形して静的検査する。プロダクション動作を明示的に保つ。 - 実行時の検証や回復可能なエラー処理にアサーションを使わない。 - コードの逐語的説明ではなく、制約や意図を説明するコメントを書く。 - 継続時間は単調時計で計測する。 - 文書化された循環依存、遅延読み込み、任意依存の事情を除き、インポートはモジュールスコープに置く。 - 高コストな型専用インポートは実行時の起動へ影響しないよう保護する。 - 意味のある最も限定的な例外を送出し、広範囲を捕捉する基底例外を導入しない。 - ドメインの失敗をプロトコル固有の応答へ変換するのは通信境界だけにする。 - 関数名には動作を表す動詞を使い、必須のライセンスヘッダーを維持する。 便乗したリファクタリングより、小さくレビュー可能な変更を優先する。依頼された動作に不要な整理は別の変更へ残す。 ## データベースへの書き込みを小分けにして、スケジューラーを遅くしない データベースセッションを受け取る関数は暗黙にコミットしてはならない。コードベースの規約に従ってセッションをキーワード専用引数にし、コミットまたはロールバックの時点はトランザクション所有者に決めさせる。 スケジューラーや保守ループ内で、上限のない一括書き込みを避ける。 1. インデックス付き列で絞り込む。 2. 上限を定めたバッチを処理する。 3. バッチ間でコミットするかトランザクションを解放する。 4. 対象行がなくなるまで続ける。 これによりロック時間、メモリ増加、他のスケジューラー処理の枯渇を抑える。既定データベースで動作を確認し、変更したクエリが基盤固有の意味論に依存する場合は代替基盤のカバレッジも実行する。 破壊的なクリーンアップコマンドを通常のトラブル対処として扱ってはならない。データベース、ボリューム、キャッシュ、ユーザーデータを削除する前に、正確な対象を確定し、必要な承認を得る。 ## 先に失敗するテストを書き、必要な時だけテストの範囲を広げる 変更対象の正確な動作を表すテストから始め、実装がなければ失敗することを確認する。次に、そのテストを成功させる最小の変更を行う。 リポジトリ推奨のテストフレームワークと補助機能を使う。 - テストツリーでソースの配置を対応させる。 - インターフェースのずれが明確な失敗になるよう、仕様に拘束されたモックを使う。 - 対応している設定上書きと時刻制御ユーティリティを使う。 - 意味のある入力差と基盤差をパラメーター化する。 - データベーステストを正確に分類し、非データベーステストをデータベース設定から独立させる。 - 不安定な整形済みログ本文ではなく、構造化イベントの名前とフィールドを検証する。 標準ライブラリや第三者依存を単独でテストしない。このコードが所有する連携動作をテストする。 最初に集中テストを実行し、次に影響を受けるパッケージの一式、静的型検査、静的検査を実行する。依存範囲が必要とする場合だけ、より広い一式へ進む。 ## CIの決まりと文書を一緒に直し、リリースノートは見える変更だけに付ける 選択的な継続的インテグレーションの動作を変更するときは、選択ロジック、そのテスト、文書を同時に更新する。コードだけ、または文章だけに存在する規則は不完全である。 ユーザーに見える変更だけに、その動作を配布する配布物のリリース用メタデータを追加する。内部リファクタリング、テストのみの作業、開発ツール、ユーザーに見えない保守には通常リリースノートは不要である。 ロック、コマンドリファレンス、スキーマ、その他の生成文書にはプロジェクトのジェネレーターを使う。生成差分は確認するが、正本側の問題を隠すために生成ファイルへパッチを当てない。 引き渡し前に、関連する整形、静的検査、型、テスト、文書、選択的検査の各関門を通す。意図的に省略した関門と、適用対象外だった具体的理由を記録する。 ## 差分を全部見直し、フォークからプルリクエストを出す 公開前にタスク全体の差分を確認する。アーキテクチャ境界、セキュリティ上の前提、テスト、生成物、リリース用メタデータ、ローカル指示がすべて整合していることを確認する。 大規模なパッケージ横断リファクタリング、広範な依存関係の追加、破壊的な移行動作の変更、未承認の外部公開を行う前に確認を求める。秘密情報の露出、必須フックの迂回、生成ファイルの手編集、明示的承認のない破壊的なバージョン管理コマンドの実行は絶対に行わない。 リモート操作の前に次を行う。 - 設定済みリモートを調べ、正式なリポジトリと貢献者のフォークを確認する。 - 正式なリモートや保護された既定ブランチへ直接プッシュしない。 - リモートの役割が不明な場合、リモートの名称変更や設定の書き換えの前に確認を求める。 - 作業の重複を避けるため、既存のプルリクエストを検索する。 - リポジトリで認められた手順により、現在の対象ブランチへリベースするか別の方法で同期する。 平易な文章で命令形かつユーザーへの影響が分かるタイトルを使う。本文では変更が必要な理由を説明し、求められる場合はAI支援を明示し、関連する課題への参照を含める。ユーザーが許可した場合、または対象者がすでにスレッドへ参加している場合を除き、自分を共同作成者に加えたり個人をタグ付けしたりしない。 完全な修正ができているなら、重複する課題を開かずプルリクエストを優先する。変更が回避策、緩和策、部分修正にすぎない場合は追跡課題を作成またはリンクし、プルリクエストと一時コード付近の両方から参照する。