← 記事一覧に戻る

理解度と速度のバランスを取ったAI駆動の開発ワークフロー

公開日 2026/02/20更新日 2026/02/23

2026/02/20時点で良い感触のワークフロー。

AIが大量に生成するコードに圧倒されることなく、コードへの理解を保ちながら、人間が主導権を握り続けるためのワークフロー。
2026/02/20時点で感触が良いものをメモしておく。
（あくまでも個人開発や厳密さをそこまで要求されない部分での運用）

最初の要件定義

  1. システムが満たすべき要件をリストとして列挙する
    • ここは自分で考えて手で書く。漏れや重複を少なく、エッジケースや分岐も細かく考える
    • 出来上がったアプリの動きを妄想する楽しいフェーズ
  2. Codex CLIの plan mode で、要件定義したい旨・システムを作る目的・想定ユーザ・1.のリストを投げる
    • ディスカッションをしてヌケモレ重複を解消する
  3. 作ってもらった plan を /docs/plan 内に配置してもらう

機能設計

  1. plan内から1機能（フェーズ1）をピックアップし、詳細度を高めた plan を、plan mode で作成する
    • 実装に近い話をディスカッションして決めていく

開発

  1. Codex CLI に フェーズ1 に対する TDD用の TODO リストを作成してもらい、.md に追加する
    • TODOリストは自分で作ってもいい
  2. TODO リストをレビューする
  3. TDDのループで実装を進める
    1. TODOリストから1件選ぶ
    2. Red: そのケースに対する失敗するテストを1つ追加 or 修正する
    3. Green: テストを通すための最小限の実装を行う
    4. Refactor: テストがグリーンの状態を維持したままリファクタリングする
    5. lint, format, knip を実行
    6. plan を更新する
    7. コミットする
    8. 問題なければ別のTODOに進む。
  4. ☝のシーケンス内では都度、質問、要件・機能・TODOのブラッシュアップを行う
  5. 定期的にテストケースの構造化を行う

繰り替えす

  1. 次のフェーズのPlanを作成して開発 -> 次のフェーズの... を繰り返す

新しいセッションに入ったとき

  • 上述のTDDの指示を毎回打ち込むのはめんどくさい
  • また、context が圧迫してきたら plan を更新させた後 /compactするが、/compact 後はワークフローが崩れる
  • そのため、上述のフローを skillsに登録している
    • 実装中の plan と次タスクを明示して指示している
# 指示の例
$workflow docs/implementation_plan_phase1-3.md の phase1.5 Case5 の続きを実装する

参考: skills

大まかに言うと、古典学派・TDDで実装してこうねという話

---
name: workflow
description: Shared collaboration workflow for implementing one TODO case at a time (t-wada style classical TDD). Assumes plan and TODO list are already agreed. Includes explicit review gates and pre-commit quality checks (lint/format/knip).
---

# Workflow

## Objective

Execute implementation with a strict one-case TDD cadence, using explicit review gates and deterministic diffs.

## Preconditions

- Plan and TDD TODO list are already agreed.
- We will start from an existing TODO item.

## Invocation

When starting work, the user says:

- `$workflow に従って、{XX} の {YY} を実装していこう`

## TDD Loop (One Case Only)

1. Pick exactly one TODO case (state the TODO id/title explicitly).
2. **Red**: add or adjust one failing test for the case.
3. Ask the user to review the test intent and failing result.
4. **Green**: implement the minimum code required to pass the test.
5. Ask the user to review the implementation.
6. **Refactor** while keeping tests green.
7. Ask the user to review the refactor.
8. **Plan Update (before commit)**:
   - Reflect the implemented behavior in the plan.
   - Mark the TODO case as completed.
   - Adjust acceptance criteria if clarified during implementation.
   - Record any design decision discovered during the case.
9. **Quality Gate (before commit)**:
   - run `lint`
   - run `format`
   - run `knip`
   - if any fail: fix minimally, keep scope constrained to the same TODO case.
10. **Commit the case**.
11. Move to the next TODO case.

## Guardrails

- Do not batch multiple TODO cases in one cycle.
- TODO must follow t-wada style, classical style TDD.
  - Behavior-first.
  - Outside-in thinking only when needed.
  - Prefer state verification over interaction verification.
  - No unnecessary mocking.
- Each TODO must represent a single observable behavior.
- Test cases must be written structurally.

  Use the following structure:
  - XXをするYY
    - XX のとき YY となる

- Test case names must be written in Japanese.
- Test names must describe behavior (condition + result), not method names.
- One test = one behavior.
- Do not test multiple branches in a single test.
- Avoid implementation detail assertions.
- Keep each step observable and explain why the change is needed.
- Prefer minimal deterministic diffs.
- Pause coding and return to discussion if disagreement appears.
- If scope changes, stop and re-align TODO/acceptance before continuing.
- Do not use English identifiers in test names unless domain terminology requires it.

- The plan must be updated before every commit.
- Implementation and plan must remain consistent.
- No commit without plan alignment.

## Commit Rules

- Commit only after completing Red → Green → Refactor and passing the Quality Gate.
- Use short imperative commit messages with prefixes such as `test`, `fix`, `refactor`, `docs`, `add`.
- Keep unrelated changes out of the commit.

効果的だと感じる文面は、TODO must follow t-wada style, classical style TDD.。

意識してること

  1. 粒度の異なる計画書を作成して、コミット前に更新する
    • 進捗把握がしやすくなる
  2. 1テストケース単位でコミットすることでPR粒度を小さくする
    • やりとりの頻度は増えるが、レビュー負荷が少なくなる
  3. テストコードを重点的にレビューする
    • テストコードを正しいガードレールに仕上げることを意識する
  4. 最初にシステムが満たすべき要件を自分で書いておく
    • 一番重要
    • 事前に考えて抜いておくと、AIが書いたコードの妥当性をスムーズに判断できる
    • 都度planで計画を立てるときにも、自分の手である程度要件を書いてからplanに投げる

悩み

  • 計画書はすぐ陳腐化する
    • 作業完了までは計画書を削除し、その際に意思決定をADRとして残すほうがいいかも
    • AIに読ませたり更新させる場合は少ない文章のほうがいいし
  • 業務では実践できていない
    • お金関係や規模の大きいシステム・チーム開発では上述のワークフローは使えていない
      • プロダクションコードめちゃくちゃレビューしてる
    • あくまでも個人での開発や厳密さを要求されない部分でのフロー