software-development

ソフトウェア開発

このスキルを使うと、プロジェクトが求める方法で変更を加えられます。つまり、フォーマットとリンティングを行い、タスクを満たす最小限の範囲にとどめ、リスクが及ぶ箇所を検証し、プロジェクトで文書化されているコマンドを使って作業し、変更の速い依存関係についてはベンダーの最新ドキュメントを確認し、内容が適切に説明されたプルリクエストとして提出できます。プロジェクトに関わるあらゆるタスクでこのスキルを使ってください。これは基本となるスキルであり、ほかのより具体的なスキルもこれを土台にしています。

タスクに関係するリファレンスセクションだけを読み込んでください。各セクションの詳細は以下のリンク先にあります。

この文書における「MUST」「MUST NOT」「REQUIRED」「SHALL」「SHALL NOT」「SHOULD」「SHOULD NOT」「RECOMMENDED」「MAY」「OPTIONAL」というキーワードは、RFC 2119 の記述に従って解釈してください。

独立した操作

ターンの料金は、そのターンで何をするかではなく、ターンが含むコンテキストの量で決まります。1つの操作を発行するターンも、互いに無関係な複数の操作を発行するターンも、料金はほぼ同じです。料金はターン単位で決まり、ターンに含まれる操作の数では決まらないためです。したがって、互いに依存しない N 個の操作を N 回のターンに分けると、同じ N 個の操作を1回のターンでまとめて発行する場合のおよそ N 倍の費用がかかりますが、1回のターンで実行する場合以上の成果は得られません。

独立した操作に関するドキュメントでは、次の内容を説明しています。

• 料金体系の詳しい根拠 — ターンの何に対して料金が発生するのか、また、倍率が操作数ではなくターン数になる理由
• Good/Bad の例を通して示す依存関係テストを使い、ある操作が別の操作の結果に依存するかどうかの不確実性を解消する方法
• 1つのターンに含める操作数について、数値目標を設けていない理由
• change-management.md の段階的変更ルールとの見かけ上の矛盾を解消する方法

以下はルールそのものであり、追加の参照義務を定めるものではありません。このスキルが適用されるすべてのターンを拘束し、より限定された状況だけに適用されるものではありません。つまり、1つのターンでまとめて発行できる、相互に独立した操作があるかどうかをこのルールが判断します。そのため、常に参照を促すリンク先に置くのではなく、ここに直接記載しています。

ガイドライン：

• 互いに依存しない操作は、連続する別々のターンに分けず、同じターンで発行しなければなりません（MUST）。
• 対象、引数、または実行の必要性が別の操作の結果によって決まる操作を、そのターンにまとめてはなりません（MUST NOT）。その操作は依存しているため、まとめると誤った対象に対する呼び出し、または本来実行すべきでない呼び出しが発生します。
• 次のステップに進む前に変更を検証しなくてもよい、という意味にこのルールを解釈してはなりません（MUST NOT）。そのケースには change-management.md の「段階的に変更する」が適用されます。このようなステップは、前のステップの検証結果によって必要性が決まるため、構造上依存しています。したがって、このルールの対象外になるのは例外だからではなく、まとめて発行する操作に含まれないためです。

コード品質

code-quality.md を参照してください。以下の内容が記載されています。

• 変更後に format → lint → fix → re-lint のループを実行すること
• 言語の規則への準拠とインポートの整理
• コメント構文を持たない形式で、何をコメントと見なすか、またプログラムがデータとして読み取るフィールドが対象外である理由
• コメントの文体 — 小文字の文章を使い、すべて大文字の強調を避けること、および本来の大文字小文字の表記を維持するもの
• コメントが満たすべき適格性の基準 — コードを読んだり追ったりすれば分かることは何も書かず、修正方法として言い換えではなく削除を選ぶこと
• ソースファイルにおけるドキュメントコメントと説明コメントの規約。行コメント形式、説明コメントの文章量の目安（約300文字）、およびどちらの種類も、作業の経緯ではなくコードを説明するようにするコメント対象の基準を含みます
• TODO(#123): の規約、そのマーカーを付けるに値する未完了コードの判定基準、解決先となる追跡可能なフォローアップ、および識別子や URL を含めてもよい標準化された形式
• コメントに記載できなくなった仕様、ドメイン用語、決定の根拠、またはファイル内に留めるべき圧縮できない「理由」の記載先

変更管理

change-management.md を参照してください。以下の内容が記載されています。

• 不具合の修正、レビューでの指摘への対応、または動作のリファクタリング
• タスクの範囲内にとどめること
• 症状にパッチを当てるのではなく、根拠のある原因と担当者まで修正の経緯をたどること
• 共通の原因や一時的な緩和策を含め、一貫性のある対処方法を選ぶこと
• 段階的に変更し、それぞれを独立して検証できるようにすること
• 新しいパターンを導入する前に、既存のパターンに従うこと
• 依存関係を追加するかどうかを検討すること

プロジェクトのドキュメント

project-docs.md を参照してください。以下の内容が記載されています。

• プロジェクト固有の操作を実行する前に、プロジェクト独自のコントリビューター向けドキュメントを確認すること
• そのドキュメントに記載がない場合、コマンドを推測せず人に確認すること
• 承認を得たうえで回答を記録し、次のタスクで参照できるように文書化すること

継続的に更新されるドキュメント

プロジェクトでは、プロダクト自体についてのドキュメント、つまり、プロダクトの概要、ドメインで使われる言葉、現在の動作、そしてプロダクトを制約する決定事項を記録するドキュメントを維持している場合もあります。また、これらを一つのツリー内にまとめている場合は、その隣に置かれた規約や運用手順の構成も記録します。このドキュメントは、上記のコントリビューター向けドキュメントとは異なる対象者に向けたものであり、独自の管理者がいます。プロジェクトが継続的なドキュメント機能を備えている場合、その機能が、ドキュメントをいつ参照するか、変更に伴ってどの内容をどのように修正する必要があるかを示します。このセクションはその機能へ案内するものであり、規則を重ねて記載することは意図的に避けています。プロジェクトにその機能がない場合、特に必要な対応はありません。

ガイドライン：

• プロジェクトが継続的なドキュメント機能を備えている場合、ドキュメントに記載された動作に関わる変更を行う際は、必ずその機能を参照し、ここに記載された要約ではなく、その機能が示す義務に従ってください。
• 両方が当てはまる場合は、時制に応じて必ず振り分けてください。これから構築するものの仕様は、プロジェクトのプロダクト要件に関する慣行に従います。上記の機能が対象とするのは、すでに存在するものの説明だけです。どちらの管理者に委ねることもせず、この区別をここに明記するのは、判断を誤るとどちらの管理者も関与しなくなるためです。

検証

verification.mdでは、以下について説明しています。

• 不具合の修正やレビューに基づく変更に適した検証方法の選択
• 回帰、ベースラインのソース、生成済み／ローカル状態、利用できないルートの証拠を通じたチェック失敗の診断（ベースと現在の状態で同一の失敗が起きる場合を含む）
• 検証方法を選ぶ前に、変更されたファイルと、それによってリスクにさらされる出力面を対応付ける方法
• 実行前に、独立した期待結果と識別力のあるチェックを用いて、壊れやすい必須事項を計画する方法
• 変更を完了と判断する前に確認する手動検証手順と、合格したゲートがその手順に含まれない理由
• スキルの習得とは別に、適用されるルールと有効な例外に照らして、現在の統合済み出力を確認する方法
• 対象、範囲、プラットフォーム、観測した段階に基づいて証拠の範囲を限定し、省略されたチェックや不十分なチェックを未検証のままにする方法
• 必要な動作を損なわずに、修正が意図した結果を達成していることを確認する方法

最新の外部ドキュメント

current-docs.mdでは、以下について説明しています。

• プロジェクトが依存する、変化の速いフレームワーク、サービス、ツールについて、最新の公式ドキュメントを参照するタイミング
• 公式ドキュメントを一次情報として扱い、参照した内容を報告する方法

コミットメッセージ

コミットメッセージのヘッダー形式（使用可能なタイプ、スコープ、説明文の規則、破壊的変更を示すマーカー、SemVer との関連、実行可能なヘッダー検証ツール）は、同じ規約のもとでプルリクエストのタイトルも規定する、プロジェクトの Conventional Commits のプラクティスに従います。コミットメッセージを作成するとき、またはプルリクエストにタイトルを付けるときは、必ずこの機能を参照してください。このスキルでは、形式を意図的に再掲していません。

プルリクエストの説明

pull-request-descriptions.mdでは、以下について説明しています。

• 説明文の対象（これから差分を読む開発者）と、そこから導かれるおよそ 200 語という上限
• プルリクエスト本文に含める内容と、「理由」を先に述べるべき理由
• API で作成した本文に、リポジトリのプルリクエストテンプレートを再現する方法
• Issue のリンク付け、本文の差分で検証可能な基準と指定されたリポジトリ外の基準（証拠へのリンクを含む）、リスクの開示、レビュアー向けの案内
• レビューの各ラウンドを通じて説明文を最新の状態に保つ方法

トピック別スキル

topic-specific-skills.mdでは、以下について説明しています。

• 計画、説明、実装、検証、レビューに入る前に、影響を受ける責任領域に基づいて該当するスキルを選択する方法
• 範囲を限定した構造的な調査と、スキル本文全体および適用される参考資料に基づく判断を区別する方法
• 新たに影響を受ける作業が発生したときに、最初に選んだ範囲を上限とみなさず、選択を再評価する方法