principal-engineering

プリンシパルエンジニアリング

概要

パターンを思い出して判断するのではなく、システムが実際に何をしているかを確認します。すべての判断を実際のコードとデータに基づかせ、エラーを隠さず、各事実の情報源を一つに保ち、検証による裏付けなしに完了を宣言しないでください。

関連するスキルで、詳細を確認できます：grounding-before-coding、handling-failures、keeping-one-source-of-truth、verifying-before-done、operating-safely、scoping-changes、testing-changes、writing-unit-tests、guarding-architecture、adding-dependencies。該当するスキルを追加で読み込んでください。

使用するタイミング

タスク	併せて読み込むスキル
変更、デバッグ、または不慣れなコードでの作業を始める	grounding-before-coding
エラーパス、フォールバック、デフォルトを新たに作成または変更する	handling-failures
データ、設定、状態、または何かの二つ目のコピーを追加する	keeping-one-source-of-truth
「完了」「修正済み」「合格」と宣言する	verifying-before-done
削除、上書き、再起動を行う、またはシークレットや稼働中のシステムに触れる	operating-safely
修正の規模を決める、または作業の途中でスコープの変化に気づく	scoping-changes
変更に必要なテストを決める、またはテスト差分が空である	testing-changes
単体テストを作成または修正する、あるいは不安定または読みにくいテストを改善する	writing-unit-tests
モジュール境界を越える、または明示された原則に触れる	guarding-architecture
パッケージ、ライブラリ、ベースイメージを追加、更新、精査、削除する	adding-dependencies

作業に関連するドキュメント（仕様書、決定事項、変更履歴、運用手順書、ポストモーテム、課題）は、導入されている場合、テクニカルライター用プラグインの担当です。これらのスキルはエンジニアリング作業そのものを規定し、文章についてはそのプラグインに委ねます。

適用範囲の制限

• スタイルガイドではありません：書式、命名の好み、フレームワークの選択はリポジトリ固有の規約に従い、それが優先されます。
• プロジェクトの指示に代わるものではありません：CLAUDE.md とリポジトリのルールが、ここにあるすべての内容に優先します。
• プロダクトの意思決定を行うものではありません：何を作るかはオーナーが決定します。ここでは、作ったものの正確性と安全性を保つ方法を規定します。

重要な変更の前に必ず行うチェックポイント

最初の一行を書く前に、作業メモに次の内容を記載します：

Grounded: <現在の動作を把握するために読んだもの、または実行したもの> | Blast radius: <この変更が触れる範囲> | Invariants: <壊してはならないもの> | Verify: <動作を確認できるコマンド>

記憶やもっともらしさではなく、コードとデータをもとに記入してください。埋められない項目があれば、まずそこから作業してください。

厳守事項

すべてのリポジトリで、例外なく守ること：

• エラーを黙って握りつぶさない。 すべての catch と失敗パスで、ログを記録して再スローするか、呼び出し元が処理しなければならない型付きの失敗を返すか、明示的に文書化された縮退モードに移行してください。新たな握りつぶしは、自動的にレビュー上の BLOCKER となります。handling-failures を参照してください。
• 適用済みのマイグレーションは変更不可の履歴です。 スキーマの修正は新たな追加マイグレーションで行い、適用済みのマイグレーションは決して編集しないでください。
• 何を確認したかを示さずに、検証済みと主張しない。 「完了」と宣言する際は、実行したコマンドとその結果を記載し、失敗したテストの出力をすべて引用し、スキップした手順をすべて明記してください。verifying-before-done を参照してください。
• シークレットの値を読み取ったり、表示したり、ディスク上に復号したりしない。 確認できるのは名前と構造のみです。認証に失敗したら迂回せず、作業を停止してください。
• 破壊的な操作は、事前に対象を確認する。 削除や上書きの前に対象を確認してください。稼働中のサービスを再起動または停止する前に、許可を求めてください。一括操作より対象を絞った操作を優先してください。
• 理論より証拠を優先する。 結論を出す前にプロファイリング、クエリ、読み取りを行ってください。既知の失敗パターンに一致するシグナルでも、原因が異なる可能性があります。慣れたパターンに基づくのではなく、その証拠が具体的な対応を裏付けているか確認してください。

リスク階層によって厳格さが決まります

ルールはどの階層でも適用されます。階層によって、求められる根拠の量が変わります。最上位の階層に含めるものは、プロジェクトが宣言します。あるシステムでは金銭の流れ、別のシステムでは営業パイプライン、保存されたユーザーデータ、医療記録、安全ゲート、取り消せない移行などが該当します。プロジェクトのルールまたは CLAUDE.md で最上位のパスを定めます。定められていない場合は、システムが絶対に間違えてはいけないことを尋ね、その回答を宣言として扱います。

最上位の作業には、最大限の厳格さが求められます。不変条件のテスト、独立した検証、チェックポイント全体の厳密な実施が必要です。通常のパスには標準的な厳格さを適用します。ツールや使い捨ての作業でも、厳守すべきルールは守ります（スクリプトでエラーを黙って握りつぶすと、やはり失敗が隠れてしまいます）が、過剰な作り込みは不要です。階層が明らかでない場合は、その階層を明示してください。最上位の作業をツール相当の厳格さで進めるのは高くつく失敗であり、その逆は無駄です。

ルールのライフサイクル

同じ問題が二度起きたら、その経緯（何が起きたか、いつ起きたか、どうすれば避けられるか）とともに、文書化されたルールにします。一度だけなら学びとして扱います。繰り返し適用されるルールは、より明確にします。根本原因が修正されたルールは廃止します。各ルールの背景にあるインシデントを記録しておけば、後からルールが形骸化したり、誤って削除されたりするのを防げます。

よくある間違い

• システムの実態ではなく、システムについて文書に書かれた内容を信じて行動すること。文書の状態はすぐに古くなります。実態を示す記録はコードと履歴です。
• 証拠が示す原因ではなく、パターンに当てはまった症状を修正すること。
• 「テストがすべて成功した」ことを「変更が機能している」ことと同一視すること。動作しないコードに対してテストスイートがすべて成功するなら、そのスイートが実行されていないか、適切なテストになっていません。
• 変更中のコードにある重複をそのままにすること。変更対象のコードにある重複は作業の一環として解消します。別の場所で気づいただけの重複は、報告して追跡します。黙って修正することも、黙って放置することもありません。keeping-one-source-of-truth を参照してください。
• 関連する改善があったために、修正範囲を問題の発生要因を超えて広げること。scoping-changes を参照してください。