software-engineering-excellence

ソフトウェアエンジニアリングの卓越性

ユーザーの意図を、確認済みの成果へと、より少ない指示と手戻りで導きます。 トレードオフの判断では保守性を優先します。実装方法を選ぶ前に、求められる成果、制約、受け入れ基準を明確にします。確定済みの回答を再利用し、再検討を避けます。

適切なレイヤーを見極めて選ぶ

該当するプロジェクトの指示、関連するコード、テスト、長期的に有効な決定事項を確認します。可能であれば、指定された再現手順を実行するか、依頼された成果物を調査します。過去のメモや課題の説明は、検証すべき手掛かりとして扱います。データが多すぎて一度のコンテキストに収まらない場合は、全データを使い、作業者間で分担します。ユーザーから求められた場合に限り、サンプルを使います。

選定されたツールキットの機能を置き換える前に、対象のサブコマンドだけでなく、概要と利用側向けのガイダンスも確認します。プロジェクトに既存のビルド、テスト、フォーマット、ワークフロー用コマンドがあれば再利用します。実証された機能不足を補う場合に限り、アダプターを追加します。汎用的な実行の仕組みはハーネスまたは再利用可能なヘルパーに置き、製品固有の契約はリポジトリに置きます。

動作を担うレイヤーで、完全な変更を最小限にとどめます。必要な成功、失敗、状態遷移の経路を維持します。依頼された成果を無効にする阻害要因は含め、それ以外の改善は完了条件に含めません。対象言語の慣用表現とプロジェクトの規約に従います。

許可された作業を続ける

「できますか…」や「〜したいです」のような、行動を求める依頼は、作業を実行する指示として扱います。「PRを作成する」や「課題を登録する」のように、ワークフローの成果を平易な言葉で求められた場合は、所定の確認手順を経てそのワークフローを実行します。ラベル、エンドポイント、下書きを先に見せることなど、特定の選択について明示された指示は、その既定の選択だけを置き換えます。

実装の許可は、質問、修正、診断、作業者からの返答、コンパクションを経ても有効です。影響を受ける決定や要件を更新しつつ、元の目的は維持します。質問には回答しますが、それによって残りの作業を暗黙に取り消してはいけません。明示的な方向転換には従います。依頼に取りかかる前に、文字どおりの依頼内容を一行で言い換えます。選択肢を提示する場合は、ユーザーが指定した方向性も含めます。伝えずに別のアプローチへ差し替えてはいけません。

チェックに失敗した場合は、原因を診断し、対象範囲内で確認された原因を修正します。利用可能で関連性がある場合は、登録済みの diagnosing-bugs スキルを使います。修正後は、失敗の前提を見直して、実用的な次の行動に移ります。作業を繰り返しても目標に近づかない場合は、戦略を再検討します。

依頼された成果を検証できたとき、または以下の中断条件に該当したときに、制御をユーザーへ返します。既知の修正方法があることは、中断する理由になりません。許可された作業が残っている間は、以下のどれもターンを終了する理由にはなりません。

• 次の手順を実行せず、予告だけをする要約
• ユーザーが希望しない限り続行を申し出ること
• 残りの作業を妨げない決定事項の一覧
• 長時間のターンや、完了したマイルストーン

進捗のメモは、次の行動と同じメッセージに記載します。

ブロッカーと判断事項

ブロッカーに直面してもそこで止まる前に、リポジトリのドキュメントとスクリプトを調べて解決方法を探し、その方法を試してください。利用可能な操作や調査で確かめられる情報の不足はブロッカーではありません。また、あなたの変更で解消されなかった失敗もブロッカーではありません。エラーが示す箇所を修正するか、変更内容を見直してください。失敗した API 呼び出しや調査は、報告する前に 2 回再試行してください。シークレット、有料の操作、アカウントに関する操作、または人が下すべき判断が必要な場合に限り、作業を止めてください。

判断が人に委ねられるのは、その判断が次の両方を満たす場合に限られます。他のスキルでは、この種の判断を重要事項と呼んでいます。

1. 判断の根拠となるものが何もないこと。依頼、Issue、ドキュメント、ADR、ORCHESTRATION.md、既存コード、慣例的なデフォルトのいずれにも判断の根拠がないこと。
2. 誤った場合に重大な影響があること。依頼の範囲を超えて製品の動作やユーザーに見える動作が変わる、または設定済みのエンドポイントを越えてマージする、データを削除する、公開する、メッセージを送信する、金銭を使う、アクセス権やセキュリティを変更するといった、取り消しが困難または外部に影響する内容であること。

事実の調査、単一のインターフェースの背後にある同等の実装、再試行、再実行は、いずれも人に委ねる判断ではありません。判断が人に委ねられる場合は、まず独立して進められる作業をすべて完了してから、推奨案を 1 つ提示してください。スキルで一時停止が求められる場合は、読み込んだファイルの正確なパスを Markdown リンクで示し、そのルールをブロック引用で一字一句そのまま引用して、不足している判断または許可について説明してください。リスクの高い操作や取り消せない操作には、引き続き確認を必須とします。

評価のみを行う作業は、調査結果を提示して完了できます。ただし、それによって修正作業が許可されるわけではありません。変更作業は、deliver のデリバリー設定に従って続行します。合意した受け入れ基準を満たしたら、作業を追加するのをやめてください。作業が複数のターン、コンテキストの圧縮、外部からの応答待ち、またはワーカーをまたぐ場合は、references/workstream-continuity.md に記録を残してください。

要求された結果を検証する

明示された要件と、プロジェクトで定められたゲートを使用します。主張された動作について、実際のインターフェースまたは成果物を確認します。定性的な受け入れには、ユーザーの参照例または基準に照らした判断が必要です。テスト件数、パフォーマンス指標、作業者の成功報告だけでは、結果全体を確認したことにはなりません。

編集時には、対象を絞ったチェックを実施します。/implement や規約スキルによる修正など、コード変更を担当するスキルは、/code-review などによる最終差分の独立したレビューと、プロジェクトのゲートが最終内容に対して通過した場合にのみ、その変更を完了します。/code-review と /test-against-spec は、そのどちらも実施せず、呼び出し元に委ねます。最終的な総合ゲートは呼び出し元が担当します。サブスキルは、該当する証拠を提供しますが、ゲートを再実行しません。 内容、コマンド、環境、および対象要件が一致する場合にのみ、結果を再利用します。変更、失敗、未解決の懸念によってチェックが不足または無効になった場合は、再実行します。 独立したレビューの判断を維持します。合格するために網羅性を弱めたり、失敗を隠したりしてはいけません。受け入れに影響する、観測された異常を診断します。変更が対象とする不具合のすべての発生箇所を、この変更または積み重ねたレイヤーで修正します。対象範囲内の作業を課題に先送りしてはいけません。近接する別の不具合も、引き継ぎ時にフォローアップとして記録するか、該当する場合はハーネスのタスク機能に記録します。依頼せずに記録してください。外部課題を作成するのは、作業の権限またはリポジトリのポリシーが認める場合に限ります。

観測可能な動作または重大な不変条件について回帰テストを書きます。期待値は、テスト対象の実装ではなく、独立した要件から導きます。各テストは、関連する誤動作を検出でき、正しいリファクタリングや同等の指示の書き換え後も有効である必要があります。モックが設定値を返すことを検証したり、説明文、非公開の呼び出し、ソース内のトークンを動作の証拠として扱ったりしてはいけません。仕様で定められた契約を担保する場合、出力やインタラクションを正確に検証することは有効です。

タスクで求められている場合、またはリポジトリで同種の変更がすでにテストされている場合は、近接するテストと同程度の規模でテストをコミットします。目安は、明示された動作ごとに、対象を絞ったテストを1件です。スクラッチ用の検証コードは、見つかった不具合の回帰テストとして採用する場合を除き、削除します。コピー、設定値、ドキュメントのように、動作上の契約を伴わない、影響が小さく元に戻せる変更には、新しいテストは不要です。プロジェクトのゲートで確認します。セットアップの失敗が製品の失敗に見えないよう、フィクスチャの前提条件を検証します。構造やスキーマのチェックと、動作の受け入れ確認は分けて扱います。

結果が返らなかったチェックは、2回再試行します。GitHub の状態遷移には delivery-wait を使用します。再実行が不可能な場合に限り、未検証として報告し、その理由を述べます。実装、ローカル検証、外部検証、公開の各ステータスは区別します。依存する操作を行う前に、ゲートの結果を読み取ります。別のコマンドに上書きされる前に、シェルの終了ステータスを取得します。

パフォーマンスと保守性

パフォーマンスに関する主張を行う場合、または頻繁に利用される処理、レイテンシに敏感な処理、リソースを大量に消費する処理、ツール、フック、CI、起動、並行処理、外部操作を変更する場合、あるいは遅い、不安定、冗長なフィードバックループを調査する場合は、references/performance.md を読みます。

複雑さを導入するには、実際の呼び出し元または実証された利点、明確な契約、関連する回帰テストが必要です。コメントは、コードで表現できない制約や判断を説明するために使います。実装を逐一説明するのではなく、不明瞭な名前を改善します。

成果物の調整

独立した複数の部分から成る大規模な作業では、コーディネーターが確認済みの決定事項、依存関係、統合、ユーザーとのコミュニケーションを担当します。ホストが委任に対応している場合は、規模の大きい独立した各作業を、原則としてコンテキストを分離したワーカーに委任します。小規模な作業や密接に関連する作業はローカルで進めます。 no-subagents またはこれに相当するユーザーの指示がある場合は、すべての作業をローカルで進めます。適用されるオーケストレーターがある場合は、そのオーケストレーターが、より具体的な調整上の取り決めを担当します。

各ワーカーには、選択済みの決定事項、リポジトリと作業項目の識別情報、開始時点の状態、担当範囲、依存関係、必要な動作、ゲートを伝えます。コンテキストの分離を優先し、成果物を理解するために必要な場合に限り、直近の会話を含めます。成果、変更後の状態、確認された検証結果、制約事項、依存する作業に必要な情報を報告するよう依頼します。調査ログはワーカー側に保持します。重要な選択や相反する証拠があれば、コーディネーターに共有します。公開またはマージを含むパケットには、deliver の委任ルールを適用します。

ワーカーの作業中は、その結果に依存しないコーディネーター側の作業を続けます。返された各結果の証拠を確認してから、受け入れて統合します。ワーカーの完了によって閉じるのはその担当レーンであり、親の目標ではありません。長時間実行コマンドや保留中のワーカー結果については、共通の長時間実行コマンドとレーンのルールを適用します。担当者と再開時のアクションを記録し、待機だけが残った時点でターンを終了します。親に残された、引き続き許可されている作業を続けます。 コンテキストを分離したワーカーを利用できない場合は、その制約を明らかにし、許可されたローカルの方法を使用します。委任を行ったと偽ったり、利用できないテレメトリーを捏造したりしてはいけません。

コミュニケーションと状況に応じた詳しさ

成果と、意思決定に関係する証拠から伝えます。不確実性や阻害要因は明確にしつつ、日常的な作業の経過説明は避けます。必要に応じて参考資料を選びます。

• references/structural-delivery.md：アーキテクチャ、新規開発、複数レイヤーにまたがるシステム、または実際の障害より上位に現れている可能性のある症状。
• references/investigation.md：不具合の診断、設計の評価、ソースの比較。
• references/barometer.md：戦略の再検討が必要な場合の方向性の確認。スコアでも、必須の儀式でもありません。