個人開発で実践するハーネスエンジニアリング/CodexのSkillパイプラインで再現性を高める
はじめに
最近の個人開発では, Codexで実装することがかなり増えました。
実装は速くなります。ただし、毎回同じ品質で進むとは限りません。
- 要件が曖昧なまま実装へ進む
- テストは通ったが、意図した仕様とずれている
- 数週間後に「なぜこの判断をしたのか」が分からない
そこで最近は、Codex の Skill を工程ごとに分け、要件整理から PR 作成までをパイプラインとして進めています。
狙いは「AI に全部任せること」ではありません。
同じ種類のタスクを、同じ確認順序と判断基準で進めやすくすることです。
なぜcodexを使っているか
これまではcursor 1本でやっていたのですが、スマホではGPTを使っているので、それならばGPT Plusにしてcodexも使ったほうがコスパがいいと思ったから。またいずれはスマホからタスクを実行したいと思っており、その予行も兼ねて。
ただし、github copilotも併用して微修正などは補っています。(githubとの親和性も高い)
何をパイプライン化しているか
本題です。普段の開発フローを、次のような Skill に分けています。
以下では、プロジェクト固有の名前ではなく役割が分かる名前で表記します。
| Skill | 役割 |
|---|---|
task-pipeline |
現在地点を判断し、次の Skill と gate を決める |
task-planner |
壁打ち、要件整理、task document / issue の作成 |
task-builder |
task document に基づいた実装 |
backend-test-runner |
backend の実行検証 |
frontend-screen-checker |
ブラウザでの画面確認 |
task-evaluator |
仕様、diff、検証結果を見た独立評価 |
task-release-handoff |
commit、push、PR 作成前の最終確認 |
親となる task-pipeline は、何でも自分で実行する Skill ではありません。
- 今は計画段階なのか
- 実装が終わり、検証へ進めるのか
- 検証結果が揃い、評価してよいのか
- commit や PR の前に止めるべき問題がないか
を確認し、担当 Skill に渡す役割にしています。
ポイント1: task document を作業の中心に置く
各タスクでは、最初に Markdown の task document を作ります。GitHub Issue などで管理しても同じ考え方です。
残す内容は、たとえば次のようなものです。
- 背景と目的
- 今回やること / やらないこと
- 受け入れ条件
- 壁打ちで決めた方針
- その時点では保留にした判断
- 実装内容と検証結果
- commit / PR まで進んだかという状態
状態は、以下のように簡単な形式で記録しています。
## パイプライン状態
- 状態: planned | changed | verified | pushed | pr-opened | blocked
- Backend検証: pending | pass | fail | gap | not-applicable
- Frontend検証: pending | pass | fail | gap | not-applicable
- Evaluation: pending | pass | revise | fail
- Commit: pending | <sha>
- PR: not-created | <url>
- 未解決事項:
task documentテンプレ
# <タスクタイトル>
## 概要
- 目的:
- 背景:
- スコープ:
## 受け入れ条件
- [ ]
- [ ]
## やること
- [ ]
- [ ]
## やらないこと
-
-
## 壁打ち・意思決定メモ
- 検討したこと:
- 決めたこと:
- 理由:
- 保留したこと:
## 未確認事項
-
## 実施内容
- 実装後に追記
## 変更方針
- 必要に応じて追記
## 関連ドキュメント修正
- 更新対象:
- 修正有無:
## 検証結果
- Backend:
- Frontend:
- その他:
## パイプライン状態
- 状態: planned
- コード変更: pending
- Backend検証: not-applicable
- Frontend検証: not-applicable
- Evaluation: pending
- Final review: pending
- Commit: pending
- Push: pending
- PR: not-created
- 未解決事項:
これが個人開発ではかなり便利です。
- 新しい Codex セッションでも、前提を読み直して再開できる
- 自分自身も、後日「なぜこうしたか」を追える
- 壁打ち時の迷いや小さなメモも残る
- きれいな仕様書ではないが、過去タスクが雑多なナレッジとして蓄積する
コードだけを見ると「何を変えたか」は分かっても、「なぜその選択をしたか」は残りにくいものです。task document や issue が残ることで、判断の履歴も開発資産になります。
ポイント2: 次へ進める条件を決める
Skill には「何をするか」だけでなく、「何が揃ったら次へ進めるか」を書いています。
| 遷移 | gate |
|---|---|
| 計画 -> 実装 | 目的、スコープ、受け入れ条件が明確 |
| 実装 -> 検証 | 変更内容と影響範囲が記録済み |
| 検証 -> 評価 | 必要な検証が pass、またはリスクを理解した gap
|
| 評価 -> release | 独立評価が PASS
|
| release -> commit / PR | 対象 diff と送信内容を人間が確認 |
また、次のような場合は止まるようにしています。
- 検証が失敗した
- 検証できない項目があり、リスクをまだ受け入れていない
- 評価で修正が必要になった
-
.env、credential、生成物、無関係な差分が commit に混ざる - CI が失敗した
自律的に進める範囲を広げるほど、停止条件の明示が効いてきます。
ポイント3: 実装、検証、評価を分ける
実装した Codex に、そのまま「問題ないよね」と判断させるだけでは不安が残ります。
そのため、役割を分けています。
-
task-builder: task document に沿って変更する -
backend-test-runner/frontend-screen-checker: 動作の証拠を取る -
task-evaluator: 受け入れ条件、仕様、diff、検証結果を照合する -
task-release-handoff: 公開してよい差分だけを確認する
テストが通ることと、作るべきものを正しく作ったことは別です。
- 仕様を読み違えていないか
- UI 変更なのに画面確認が抜けていないか
- ドキュメント更新が必要ではないか
- 無関係なファイルが commit に入っていないか
を別工程で確認することで、PR まで進める判断が安定します。
ポイント4: Skill のプロンプト自体もチューニングする
パイプラインを作っても、Skill の指示文が曖昧なら、毎回同じようには動きません。
Skill の調整では、mizchi さんの プロンプトの再現性をAI に自動チューニングさせる方法 を参考にしています。
考え方はシンプルです。
- Skill を書いた本人の文脈を持たない AI に、実際のシナリオで実行させる
- 「不明瞭だった点」「指示がなく裁量で補った点」を報告させる
- 典型ケースだけでなく、端のケースでも試す
- 指摘された曖昧さを Skill に戻し、別の新しい実行で再評価する
Skill を書いた直後は、自分の頭の中にある前提を補いながら読んでしまいます。別コンテキストで実行すると、意外なほど判断基準の抜けや曖昧な語が見つかります。
この方法を入れることで、パイプラインの再現性を「自分の感覚」だけではなく、実行結果から改善しやすくなります。
たとえば最近は、Andrej Karpathy 氏の Skill 設計例を参考にしながら、各 Skill の責務や停止条件を少しずつチューニングしています。
ポイント5: ツールではなく安全な到達点を決める
GitHub 作業では、環境によって利用できる CLI や connector が異なることがあります。
そのため、特定のコマンドを必須にはせず、次のように考えています。
- commit や push は利用可能な安全な手段で進める
- PR 作成や CI 確認ができない場合は、最後に安全に完了した地点で止まる
- 何が不足して止まったのかを task document に残す
実行環境の違いで全工程が止まるより、どこまで安全に完了したかが明確な方が扱いやすくなります。
これは Harness Engineering なのか
このスタイルは、Harness Engineering の小さな実践例 と呼べると思っています。
OpenAI は Harness engineering: leveraging Codex in an agent-first world で、agent が信頼できる仕事を行えるように、環境、意図、フィードバックループを設計することの重要性を説明しています。
個人開発の Skill パイプラインは、大規模な自律開発基盤ではありません。それでも、やっていることは同じ方向です。
- 作業を工程へ分解する
- 状態と判断を task document / issue に残す
- 検証と評価のループを作る
- Skill 自体も実行結果から改善する
- 危険な操作の前には止まれるようにする
Codex の性能だけに期待するのではなく、Codex が再現性を持って働ける工程を作ることが、最近の個人開発で意識していることです。
まとめ
Codex の Skill パイプラインを作ってから、個人開発で意識することが少し変わりました。
- 実装を速くするだけでなく、判断を残す
- 一度の良い結果ではなく、別タスクでも再現できる形にする
- 失敗したら、注意して使うのではなく Skill や gate を更新する
- 過去の task document / issue を、雑多でも使える知識として蓄積する
個人開発では、工程を整える作業も自分のプロダクト開発の一部です。
Codex がコードを書く時間を短くしてくれるなら、自分は Codex が安定して仕事を進められる仕組みを育てる。今はそのバランスが、かなりしっくりきています。
Discussion