実装

検証駆動型コーディングと緊密なフィードバックループ。64以上のプロジェクト全体で追跡された21,321の操作、612のデバッグセッション、2,476の会話履歴から抽出。これらは確実に動作するコードをリリースするパターンです。

コアインサイト： 大体2～3回の編集ごとに緊密なループで検証します。データセット全体で修正の73%が未検証のままになっており、これが品質ギャップの最大の原因です。検証ペースが厳密なセッションは、このスキルの残りの部分が防ぐために設計されたデバッグのスパイラルを回避します。

このスキルの読み方： 以下のループとヒューリスティックは非自明な実装作業向けに調整されています。些細な修正（設定、タイプミス、1行）は5つのフェーズを引きずるべきではありません。判断を使い、計画のスコープをスケーリングし、適用されないものはスキップします。「Code Discipline」セクションは注意を促すような原則です。1行の変更の場合は、単に変更を加えます。

ループ

ほとんどの実装作業は、スケールに関係なく同じ形状を通じて流れます：

digraph implement {
    rankdir=LR;
    node [shape=box];

    "ORIENT" [style=filled, fillcolor="#e8e8ff"];
    "PLAN" [style=filled, fillcolor="#fff8e0"];
    "IMPLEMENT" [style=filled, fillcolor="#ffe8e8"];
    "VERIFY" [style=filled, fillcolor="#e8ffe8"];
    "COMMIT" [style=filled, fillcolor="#e8e8ff"];

    "ORIENT" -> "PLAN";
    "PLAN" -> "IMPLEMENT";
    "IMPLEMENT" -> "VERIFY";
    "VERIFY" -> "IMPLEMENT" [label="fix", style=dashed];
    "VERIFY" -> "COMMIT" [label="pass"];
    "COMMIT" -> "IMPLEMENT" [label="next chunk", style=dashed];
}

ORIENT. 何かに触れる前に既存のコードを読みます。Grep → Read → Read がデータセット全体で支配的なオープニングです。最初の編集前に10以上のファイルを読むセッションは、その後の修正イテレーションが少なくて済みます。盲目的な変更は最も費用のかかる開始方法です。

PLAN. スケール依存（以下参照）。些細な修正は計画が不要です。機能はタスクリストから利益を得ます。エピックは研究スワームに値します。決定は「何が相応か」であり、「常に計画すること」ではありません。

IMPLEMENT. 大体2～3回の編集のバッチで作業し、その後検証します。依存関係チェーンに従います。既存ファイルを編集する割合は新しいファイルを作成する割合に対して9:1です。これが成功したセッションで観察された割合です。エラーが表面化したら修正します。それらを蓄積するとカスケードデバッグが生じます。

VERIFY. 型チェックが主要なゲートで、速く安価です。バッチ間で実行します。テストは機能完成後に自然に適合します。コミット前に完全なスイートを実行します。

COMMIT. アトミックなチャンク。進むにつれてコミットします。検証し、特定のファイルをステージングし、コミットし、次のチャンクにループバックします。セッションごとに多くの小さなコミットが、最後に1つのメガコミットをしたパターンよりも一貫して優れたパフォーマンスを示します。詳細は下のコミットペースを参照してください。

---

Code Discipline

ループを通じて移動する方法を形作る原則であり、実行するステップではありません。Karpathyの観察から採用。LLMコーディングの落とし穴について、モデルは「あなたに代わって間違った前提を立てて、チェックすることなく実行を進める...本当にコードとAPIを過度に複雑にして、抽象化を肥大化させるのが好き...100行で十分な場合に1000行かけて肥大した構成を実装する」

これらの原則はモデルがドリフトする場所だから慎重さを促します。些細な修正の場合、計算は反転します。判断を適用し、完全な規律は適用しません。

コーディング前に考える

仮定しないでください。混乱を隠さないでください。トレードオフを表示してください。

状況	アクション
リクエストの複数の解釈	黙って選ばずに提示してください
より単純なアプローチが妥当である	そう言います。正当な場合はプッシュバックしてください
何か不明確である	停止します。何が混乱しているか名付けます。質問します
負荷を担う前提を保持している	明示的に述べます
リクエストとコード間の矛盾	進める前に表示します

ORIENT（コードを読む）は前提条件です。この原則は見つけたもので何をするかについてです：ギャップを名付けます。紛らわしい論文は書かないでください。

シンプルさ優先

問題を解く最小限のコード。推測的なものはありません。

しないでください	してください
要求以上の機能を追加する	述べられた問題を正確に解く
単一用途のコードの抽象化を構築する	まずインラインします。再利用時に抽象化します
要求されていない「柔軟性」または構成可能性を追加する	今はハードコード。必要に応じてパラメーター化します
不可能なシナリオのエラーを処理する	内部不変量を信じます。エッジで検証します
50行で十分なら200行を書く	より締まった状態に書き直します

テスト：シニアエンジニアがこれを過度に複雑と呼びますか？そうなら、シンプルにします。

外科的変更

必要なものだけに触れます。自分の散らかしだけ片付けます。

ルール	理由
隣接するコード、コメント、またはフォーマットを「改善」しないでください	diff を汚します。スコープ外
壊れていないコードをリファクタリングしないでください	スコープクリープが影響範囲を拡大します
異なる方法で行うとしても既存のスタイルを一致させます	あなたの好みよりもローカル一貫性が優れます
関連のないデッドコードに気付く → 削除しないで言及します	他のブランチ/エージェントがそれに依存するかもしれません
インポート/変数/関数を削除します。変更が孤立したもの	後片付けします
既存のデッドコードを単独にしておきます	明示的に要求されない限りスコープ外
理解していないコメントに触れないでください	Karpathy：「副作用...タスク直交」

テスト：変更されたすべての行がユーザーのリクエストに直接トレースされるべきです。

ゴール駆動実行

検証可能な成功を定義します。それが合格するまでループします。

曖昧なタスク	検証可能なゴール
「検証を追加する」	無効な入力のテストを書き、その後それらを合格させます
「バグを修正する」	それを再現するテストを書き、その後それを合格させます
「X をリファクタリング」	前後で同じテストが合格することを確認します
「動作させる」	拒否します、それが機能することを証明する実際の信号を名付けます

複数ステップの作業の場合、ステップごとに検証を含む計画を述べます：

1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]

強い成功基準を使えば独立してループできます。弱い基準は継続的な説明が必要です。

---

スケール選択

戦略はスコープに基づいて劇的に変わります。正しい重量クラスを選択します：

スケール	編集	戦略
些細 (設定、タイプミス)	1-5	Read -> Edit -> Verify -> Commit
小さな修正	5-20	Grep error -> Read -> Fix -> Test -> Commit
機能	50-200	Plan -> Layer-by-layer impl -> Verify per layer
サブシステム	300-500	Task planning -> Wave dispatch -> Layer-by-layer
エピック	1000+	Research swarm -> Spec -> Parallel agents -> Integration

スキップ計画するとき： スコープが明確、シングルファイル変更、1文で説明可能な修正。

計画するとき： 複数ファイル、なじみのないコード、不確実なアプローチ。

---

依存関係チェーン

この順序でものを構築します。フルスタック、Rust、およびモノリポプロジェクト全体で検証：

Types/Models -> Backend Logic -> API Routes -> Frontend Types -> Hooks/Client -> UI Components -> Tests

フルスタック (Python + TypeScript):

1. データベースモデル + マイグレーション
2. サービス/ビジネスロジックレイヤー
3. API ルート (FastAPI または tRPC)
4. フロントエンド API クライアント
5. API 呼び出しをラップする React フック
6. フックを消費する UI コンポーネント
7. Lint -> typecheck -> test -> commit

Rust:

1. エラー型 (thiserror enum with #[from])
2. 型定義 (structs, enums)
3. コアロジック (impl blocks)
4. モジュール配線 (mod.rs re-exports)
5. cargo check -> cargo clippy -> cargo test

主要な発見： データベースマイグレーションは、それを必要とするコードの後に記述されます。フロントエンドは逆と同じくらい頻繁にバックエンド変更を駆動します。

---

検証ペース

データセットで最も影響力のあるプラクティス。ここでの緊密なループはスキルの残りの部分をほぼ不要にします。緩いループは他のすべてのガイドラインに従うことを難しくします。

ゲート	一般的に	スピード
Typecheck	編集バッチ間	速い (主要ゲート)
Lint (autofix)	実装バッチ後	速い
テスト (特定)	機能完成後	中
テスト (完全スイート)	コミット前	遅い
ビルド	PR/deploy 時のみ	最遅

編集-検証-修正サイクル

一貫して clean なセッションを生成するパターン：~3 変更 → verify → 1 修正。厳密な比率ではなく、最適なスポット。時々1つの編集が独自の検証を保証し、時々5つの編集がクリーンにグループ化します。

デバッグスパイラルを生成するパターン：2 変更 → typecheck → 15 のカスケード修正。共有型を修正する前にコンシューマーをグリップして型カスケードを防ぎます。カスケードが開始したら、修正ドメインを分離します（エラーリカバリを参照）。

組み合わせゲートが時間を節約します： turbo lint:fix typecheck --filter=pkg は両方を1回のショットで実行します。検証を影響を受けたパッケージにスコープし、フルモノリポではありません。

実用的なヒント：

• lint チェック前に lint:fix を実行してイテレーションを削減する
• cargo build より cargo check を実行（2-3倍高速、同じエラー検出）
• 冗長出力を切り詰める：2>&1 | tail -20
• テストをタイムアウトでラップする：timeout 120 uv run pytest

---

決定木

読むか編集するか

このセッションで編集した見慣れたファイル？
  はい -> 直接編集（その後検証）
  いいえ -> このセッションで読んだ？
    はい -> 編集
    いいえ -> 最初に読む（クイック修正の79%は読むで始まる）

サブエージェント対直接作業

明確な成果物を持つ自己完結型？
  はい -> 冗長出力を生成（テスト、ログ、研究）？
    はい -> サブエージェント（コンテキストをきれいに保つ）
    いいえ -> 頻繁なやり取りが必要？
      はい -> 直接
      いいえ -> サブエージェント
  いいえ -> 直接（反復改善には共有コンテキストが必要）

リファクタリングアプローチ

変更を段階的に行えるか？
  はい -> 最初に移動、その後統合（個別コミット）
        古い横の新しいコード、古いのみを削除テスト合格後
  いいえ -> 分析フェーズ最初（並列レビューエージェント）
        ギャップ分析：古い対新しい関数ごと
        フォーカスされたタスクとしてギャップを実装

バグ修正対機能対リファクタリング

タイプ	ペース	一般的なサイクル
バグ修正	Grep error -> Read 2-5 files -> Edit 1-3 files -> Test -> Commit	1-2
機能	Plan -> Models -> API -> Frontend -> Test -> Commit	5-15
リファクタリング	Audit -> Gap analysis -> Incremental migration -> Verify parity	10-30+
アップグレード	Research changelog -> Identify breaking changes -> Bump -> Fix consumers	変数

---

エラー復旧

デバッグセッションの65%は1-2イテレーションで解決します。 残りの35%は6回以上のスパイラルリスクがあります。以下のパターンはあなたを最初のバケットに保つために調整されています。

クイック解決

• 最初に関連コードを読む（データセットで79%の成功相関）
• 明確な仮説を形成：「問題は X です、理由は Y」
• 1つのターゲット修正を行う
• 修正が実際に機能したことを確認してから先に進む

スパイラル防止

• エラードメインを分離します。 すべての型エラーを修正してからテスト失敗を追求します。2つをインターリーブするのはカスケードが複合する方法です。
• 3ストライクヒューリスティック。 同じエラーに3回の失敗した試みは、アプローチを完全に変更または段階的にあげるシグナルであり、バリエーション #4 を試す試みではありません。
• カスケード深度 > 3。 一時停止し、残りのすべての問題を列挙してから、反応的なモグたたきではなく依存関係順に修正します。
• コンテキスト腐敗。 ~15-20イテレーション後、/clear し、始めから。より良いプロンプトで clean なセッションは通常、蓄積された修正よりもパフォーマンスが優れています。

2修正ルール

同じ問題を2回修正することは /clear し、開始のシグナルです。コンテキストノイズは修正が解決するより速く複合します。

---

コミットペース

各論理チャンクを着地して検証する際にコミットします。セッションあたり多くの小さなコミットが規範です。無関連の作業を1つのメガコミットに蓄積しないでください。COMMIT ステップは次のチャンクの IMPLEMENT にループバックします。

コミットするとき

トリガー	アクション
論理チャンク完了、検証合格	コミット
移動/名前変更完了、動作変更前	コミット (move)
動作変更が移動コミット後に機能	コミット (change)
リファクタ抽出、呼び出し側がまだ合格	コミット
別の懸念に切り替えようとしている	現在のものをコミット
検証失敗または編集は推測的	コミットしないでください

レビュアーが別の diff として必要とする場合、それは別のコミットです。

ローカルスタイルをミラー

リポのファイルに最初のコミット前に、git log -10 --oneline を実行し、パターンをミラーします。品質ではなくフォーマットをミラーします。簡潔な履歴はあなたのバーを下げません。パターンが存在しない場合は従来のコミットがデフォルトです。

パターン	例
従来のコミット	feat(api): add token refresh
Gitmoji	✨ Add token refresh
チケットプレフィックス	[ENG-1234] Add token refresh
モジュールプレフィックス	auth: add token refresh
プレーン	Add token refresh

従来のコミットタイプ：feat (機能)、fix (バグ)、refactor (動作変更なし)、perf、test、docs、style (フォーマットのみ)、chore (ツーリング/deps)、build、ci。スコープはオプションですが、変更がローカライズされている場合は推奨されます。

メッセージ解剖

主題： 命令型、≤76 文字、末尾ピリオドなし、ファイル名なし。「Fix null deref in token refresh」は「Fix bug」に勝ります。従来のコミットの場合、絵文字は主題にありません。パーサーを壊します。

本文 (常に含める)：76 文字でラップ、主題から空行で分離。why を説明し、diff は what を示します。事実を述べます：「likely」、「probably」、「might」、「seems」、「appears to」を追放します。変更が何をするか分からない場合は、コミット前により多くのコードを読みます。通常2文で十分です。将来の二分探索が必要とする負荷担う context に言及します。

HEREDOC + Co-Author

常にメッセージを HEREDOC 経由で渡してフォーマットを保持します。モデルに名前を付ける Co-Authored-By トレーラーを追加します。「Claude」だけはマルチエージェントセッション全体で区別しません。

git commit -m "$(cat <<'EOF'
fix(auth): guard against null session in token refresh

Refresh racing with logout was dereferencing a freed session, surfacing
as a 500 with no log trail. Early return plus a single warn log makes
the failure mode visible without spamming on every refresh.

Co-Authored-By: Nova (Claude Opus 4.7) <noreply@anthropic.com>
EOF
)"

例

悪い	良い
fix: bug	fix(api): resolve null deref in token refresh
update stuff	chore(deps): bump axios to 1.7.4
WIP	feat(auth): scaffold magic-link sign-in flow
Added new file for users	feat(users): add bulk import endpoint
feat: it works now	feat(search): add fuzzy matching to user lookup

マルチエージェントステージング

他のエージェントは並列で作業できます：

git status                # 全体像を最初に見る
git diff --staged         # コミットしようとしているものをレビュー
git add <specific-files>  # あなたが個人的に触った唯一のファイル

git add -A または git add . を使わないでください（他のエージェントの WIP とシークレットをキャッチ）。変更していないファイルを git restore しないでください。明示的なリクエストなしに git push しないでください。プッシュは人間の呼び出しです。計画ドキュメント、スクラッチファイル、.local.md をレポから削除します。

---

アンチパターン

アンチパターン	修正
検証なしで20+編集	2-3編集ごとに検証
修正を検証なしで修正（修正の73%！）	1つの修正、1つの検証、繰り返す
チェックなしで fix -> fix -> fix チェーン	常に修正間で検証
最初に読まずに編集	編集直前にファイルを読む
メモリからテストを書く	最初に実際の関数署名を読む
コンシューマーをグリップせずに共有型を変更	共有型を変更する前に Grep すべてのの用途
1つのコミットで移動と変更を混ぜる	最初のコミットを移動、2番目のコミット変更
3試行を超えるデバッグスパイラル	アプローチを変更または段階的
早すぎる最適化	テスト合格後、最初に正確さ、その後最適化
セッション最後のメガコミット	着地するにつれて各論理チャンクをコミット
「fix: bug」や「update stuff」のようなベアタイトル	特定の主題 + why を説明する本文
本文をスキップして「時間を節約」	常に本文を含めます、2文でも
主題行のファイル名またはパス	動作を説明します。ファイルではなく
不確実な言語（「might fix」、「should work」）	事実を述べます。知らなければさらにコードを読む
git add -A / git add .	特定のファイルのみステージング
明示的なリクエストなしで git push	プッシュは人間の呼び出しです。自律的ではありません
1つの解釈を黙って選ぶ	オプションを表示します。1つにコミットする前に質問
変更に隣接するコードを「改善」	外科的にとどまります。要求されたもののみに触れます
理解していないコメントに触れる	それらを置いておきます。スコープではありません
単一使用のコードの肥大化した抽象化	関数を書きます。再利用時に抽象化
曖昧な「動作させる」ゴール	最初に検証可能なチェックを定義

---

モデル間レビュー

高リスク変更の場合、実装後に /hyperskills:cross-model-review を実行します。別のレビュアーモデルは著者と異なるブラインドスポットを持ち、実際のバグをキャッチします：マイグレーション冪等性、デバッグロギングの PII、空配列エッジケース、不足しているバッチ制限。codex review サブコマンドセマンティクスで Claude → Codex 方向を特別に望むときのみ /hyperskills:codex-review を使用します。

---

参考文献

量的ベンチマークと実装アーキタイプテンプレートについては、references/benchmarks.md を参照してください。

---

このスキルが何でないか

• ゲートではありません。 タイプミス修正のために5つのフェーズすべてに従わないでください。スケール選択は理由があります。
• コードを読む代わりではありません。 このスキルは何を実装するかではなく、どのように実装するかを教えます。
• 計画ツールではありません。 タスク分解に /hyperskills:plan を使用します。
• テストをスキップする言い訳ではありません。 「検証」は実際のチェックを実行することを意味し、diff を目で見ることではありません。