engineering-method-footguns

エンジニアリング手法の落とし穴

本番環境の Kotlin および Compose Multiplatform アプリから抽出した 9 つの落とし穴です。それぞれ references/ に短いファイルがあります。各ファイルでは、適切なパターン、実際に起こる具体的な失敗例とその理由を示す 落とし穴、およびユーザー自身のコードベースに対して実行するコマンドを記載した 検証方法 を説明しています。

このインデックスの使い方。 これから書くコード、または調査中の症状に合う項目を以下から探してください。各項目には、トピックと、その項目を参照すべき症状が記載されています。コードや修正を提案する前に、該当する可能性のあるファイルをすべて Read ツールで読んでください。どのファイルも 150 行未満です。検証コマンドに元のプロジェクトのパスが記載されている場合は、ユーザーのコードベースに対応するパスに置き換えてください。

相互参照。 ファイル内にバッククォートで囲まれた落とし穴の名前があり、それがここに記載されていない場合は、隣接するスキル領域にあります。../*/references/<name>.md を glob して開いてください。

エンジニアリング手法

• run-discriminating-experiment-first — ほぼ同じ2つのものの動作が異なる場合は、まだ異なる変数の数を数え、修正を書く前に、少なくともその半分を排除できる入れ替えまたは交換テストを1つ実行します。同じ症状に対して修正を2回以上試しても解消しない場合、ウィジェット、画面、またはプラットフォームの一方は動作するのに、そのすぐ隣にあるほぼ同じものは動作しない場合、または試すたびに時間のかかるビルドと他の人の注意が必要な場合に使います。
• noop-actual-not-platform-limit — マルチプラットフォームプロジェクトに空のプラットフォーム実装や入力をそのまま返す実装がある場合、それはそのプラットフォームでは実現できないという意味ではなく、誰も実装していないという意味です。そこで機能を実現するのは不可能だと伝える前に、依存関係で解決されたバリアントと、それを宣言するソースセットを確認します。「デスクトップ／iOSでは動作しない」機能がある場合、プラットフォームファイルが入力を変更せずに返すか、本体が空の場合、または機能をプラットフォームの制約として片付ける前に使います。
• read-build-logs-bottom-up — ビルドログは、まず末尾で結果を確認し、次に最初のエラーマーカーを探して原因を確認します。どちらからも固定サイズの範囲だけを読むのは避けてください。原因を示すメッセージと失敗を示すバナーは、出力の反対側にあるためです。バックグラウンドビルドが終了し、その結果を要約しようとしているとき、ログに理由がなく「task X FAILED」としか表示されないとき、またはフィルター結果が空で、ビルドが正常だったと判断しようとしているときに使います。
• changelog-as-war-story — 日付付きの項目を記録する、追跡対象の Markdown ファイルを用意します。各項目には、症状、仕組み、除外した原因、および回避策を削除する条件を記録し、変更と同時に項目を追加するルールを設けて徹底します。直感的でない動作に基づく修正を、後から誰かが「整理」してしまう可能性がある場合、同じ調査が何度も繰り返されている場合、または大きな落とし穴がある領域について人間やエージェントに説明する場合に使います。
• writing-agent-skill-house-style — 敵対的なレビューにも耐えられるエージェントスキルを書きます。説明には、読者が直面しているきっかけとエラー症状の両方を含め、短い概要を設け、ファイルの大部分を「落とし穴」セクションに割き、実際に実行した検証コマンドを記載します。SKILL.md の作成やレビューを行う場合、スキルが実践から得た知見ではなくドキュメントのようになっている場合、またはレビューでソースリポジトリが裏付けていない主張が繰り返し見つかる場合に使います。
• xml-to-compose-sequencing — 大規模な XML から Compose への移行は、最も難しい画面から着手して順序を決めます。主な作業はウィジェットの置き換えではなく、散在する状態の集約になると想定し、ナビゲーションによってルートのシリアライズ移行も必要になることを計画に含めます。複数リリースにわたる UI 移行を計画する場合、「移行済み」の画面が増えているのにレイアウトファイルの数が減らない場合、または次に変換する画面を決める場合に使います。
• commit-archaeology-red-flags — リポジトリの履歴を誤解しないように調べます。本文が空のコミットではファイル統計が実質的な要約になり、ネストされたリポジトリの更新では内容全体が1行のポインター変更の背後に隠れ、マージではブランチの判断の経緯が1つの件名に平坦化されます。なぜその状態になっているのかを再構築する場合、理由の説明がないコミットに blame がたどり着いた場合、または1行だけに見える変更がそれほど小さいはずがない場合に使います。
• removing-a-feature-audit-shared-handles — 新しい機能と重複する機能を削除する際は、その機能が所有しているように見えたハンドルを他に何が使っているかを監査し、他のプラットフォームにある何もしないスタブを削除し、削除が機能したかどうかを判断する前に強制停止します。同じ出力に対する2つの効果は重なり合うため、すでに外部から適用されている効果は変更後も残ることがあるからです。委譲型の連携をアプリ内実装に置き換える場合や、削除した機能がまだ動作しているように見える場合に使います。
• a-stated-rule-needs-annotated-exceptions — 例外ごとに呼び出し箇所で理由を添え、ルール自体を grep できるようにしなければ、正当な例外がある設計ルールは維持できません。そうしないと、例外と違反を区別できず、ルールは気づかれないまま形骸化します。ルールの記述場所、理由の記載場所、そのルールが実際に適用されるコードに監査範囲を限定する方法、コメントに基づくチェックの限界を扱います。明示された規約が曖昧になっている場合、意図的な対応と不注意な対応をレビュー担当者が見分けられない場合、またはファイルヘッダーにルールを書けば守られると思い込む前に使います。