Top

Workflow

開発の進め方:顧客理解と実装を分けて行き来するDevelopment workflow: separating and connecting customer understanding and implementation

AI で実装が速くなると、詰まるのは「何を作るか決めること」と「出力の検証」になる。答えを待たずに仮置きで試作して暗黙知を引き出し、作った者とは別の文脈で検証する。When AI makes coding fast, the bottlenecks shift to deciding what to build and verifying the output. I prototype on explicit assumptions to surface tacit needs and verify in a fresh context.

Big Picture

顧客理解担当と実装担当を分け、試作と問いでつなぐSeparate customer understanding from implementation, and connect them with prototypes and questions

現場と試作から要件を決める「顧客理解担当」と、約束を切って作る「実装担当」に分ける。文書でやり取りせず、動く試作と問いの Issue で2つの担当を行き来させる。Customer Understanding decides what to build from the site and prototypes; Implementation builds against approved promises. The two sides stay connected through working prototypes and question Issues.

顧客理解担当現場と試作から決める実装担当約束を切って作り検証利用者の現場試作を触り決めるPRの動く試作で要件の正本・FB問いの Issue仮置きの点を渡す起票(AC・保証)決めた要件・FBから実装セッション確認者・使い心地作った者は判定しないPR・マージ

01「要件定義担当」ではなく「顧客理解担当」を置く理由Why "Customer Understanding" instead of "Requirements Analyst"

AI で実装が速くなると、ずれたものを速く作ることが最大の失敗になる。仕様書をまとめる仕事は AI に移し、人の時間は何を作るべきかを決めることに使う。When AI makes building fast, the biggest failure is building the wrong thing fast. Spec writing moves to AI; human time goes into deciding what to build.

02設計書を先に固めず、動く試作で暗黙知を引き出す理由Why surface tacit knowledge with prototypes instead of upfront specs

利用者が慣れで回避している手間や書かれていない例外は、質問表では出てこない。答えを待って文書を重ねるより、仮置きで動く画面を先に見せるほうが、顧客自身も自分の要件に気づける。先に決めるのはデータの形だけで、設計書は読み手が要るときに実装から起こす。Workarounds users take for granted and unwritten edge cases never appear in questionnaires. Showing a working screen built on explicit assumptions lets clients recognize their own needs far faster than piling up documents. Only the shape of the data is decided upfront; design documents are derived from the implementation when a reader needs them.

03人が見る場所を「書いて渡せない判断」だけに絞る理由Why restrict human review to judgments that cannot be written down

値の照合や手順のチェックに人の注意力を使うとレビューが詰まる。人が止まるのは「約束(AC・保証)の承認」「使い心地」「マージ」だけに固定し、それ以外は別文脈の検証器で流す。Spending human attention on value matching and procedural checks bottlenecks review. Humans stop only at three gates—approving promises (ACs & guarantees), UX feel, and merge—while isolated verifiers handle the rest.

Upstream

答えを待たずに「仮置き」で作り、問いの回収と並行させるBuild on explicit assumptions in parallel with Q&A collection

受託開発で手が止まる最大の理由は、実装の遅さではなく「先方の回答待ち」にある。The biggest delay in contract development is waiting for client answers, not coding speed.

未確定を含む要件回答待ちで止めない実装担当止めずに試作仮置きで先に実装仮置き一覧へ分離問いの Issue 起票出典と仮案を添付顧客理解担当並行して照会・回収依頼主へ照会/qa-send回答を1か所に回収/qa-collect回答を反映試作で暗黙知が出る正本と実装を更新/client-next · 違えば直す

Customer Understanding

顧客理解担当:照会・回収を回し、試作から要件を決めるCustomer Understanding: run Q&A skills and decide specs from prototypes

  • 01

    照会と1か所への回収Send & centralize answers

    /qa-send/qa-collect

    照会文面を下書きして送り、照会表・MTG・チャットのどこで出た回答も問いの Issue 1か所に集約する。Draft inquiries to send, and funnel answers from spreadsheets, meetings, or chat into a single Question Issue.

  • 02

    2段階レビューと正本の更新Two-stage review & canonical spec updates

    試作を利用者より先に触り(社内レビュー)、直ったものを利用者に見せて反応を引き出す(利用者レビュー)。決まった要件を正本へマージするのはこの担当だけに絞る。Touch the prototype before users do (internal review), then show the refined version to users to draw out feedback. Only this role merges confirmed specs.

Implementation

実装担当:未確定を「仮置き」と「問い」に分けて試作Implementation: split unknowns into assumptions and question Issues

  • 03

    仮置き一覧に分離して作るIsolate in an assumption list

    AI が黙って選んだ前提がそのまま本番に残らないよう、仮に置いた仕様は一覧に明記して確定分と分ける。So silent AI guesses never slip into production, provisional choices are recorded in a dedicated assumption list separate from confirmed specs.

  • 04

    問いを起こし、回答を読むOpen questions & apply answers

    /client-next

    先方の判断が要る点は同じ変更で「問いの Issue」に起こして渡す。戻った回答は次の起票時に読み、仮置きと違えば直しの Issue にする。Items needing client decisions are opened as Question Issues in the same change. Returned answers are read on the next draft and turned into fix Issues if they differ.

Downstream

約束を先に承認し、作った者とは別の文脈で判定するApprove promises first, verify in an isolated context

エージェントは検証器が見ているものを解く。人が全差分を読む代わりに、入口で「完了条件(AC)」と「壊さない保証」を承認し、出口では別文脈の確認者が証拠付きで検証する。Agents optimize for what the verifier checks. Instead of reading every diff line by line, humans approve ACs and guarantees at the entrance, and an isolated verifier checks them with evidence at the exit.

Issue で約束を承認/issue-draftIssue だけ渡す1セッション通し実装/issue-work · 3本並行操作役 → 使い心地screen-operator別文脈の確認者issue-verifier合否と証拠証拠付き PR外れた点だけ確認手戻りを集計/rework-reviewSkill・Hook を更新再発を手順と機械で防ぐ

Verification Flow

  1. 01

    実装前に Issue で約束を切るApprove promises in the Issue before building

    /issue-draft

    後から条件を決めると、できたコードに合わせた甘い条件になる。Defining criteria after the code is written leads to lenient tests tailored to the implementation.

  2. 02

    文脈を切って新セッションで1本通しで作るBuild end-to-end in a fresh session

    /issue-work

    起票時の相談の文脈を持ち込むと、書かれていない暗黙の了解で実装が進む。Carrying over the drafting conversation lets unwritten assumptions slip into code.

  3. 03

    作った者は判定しないThe builder never judges its own work

    screen-operatorissue-verifier

    自分で書いたテストで自分の実装を確かめると、自分の解釈で合格にする。An agent testing its own code grades on its own interpretation.

  4. 04

    手戻りの原因を仕組みへ還流するFeed rework causes back into Skills and Hooks

    /rework-review

    判定がすべて通れば止まらずに証拠付き PR を出す。実装中にやり直した箇所(手戻り)は PR に記録し、繰り返す原因を集計して Skill の手順と Hook の更新へ戻す。When all checks pass, an evidence-backed PR is opened without stopping. Rework during implementation is logged in the PR and aggregated to update Skill steps and mechanical Hooks.

Sample 01 — Issue の AC と保証Issue ACs & Guarantees

## AC(完了条件)
- [ ] 確認書を送り直す画面を開くと、送り先に前回の送り先が入っている
- [ ] 前回の送り先が無い注文では、送り先を空のままにする

## 保証(壊してはいけない振る舞い)
- 送り先を書き換えて送っても、注文マスタの記録は書き換えない
## AC (Acceptance Criteria)
- [ ] Opening the resend screen pre-fills the last recipient address
- [ ] Orders without a previous recipient leave the address blank

## Guarantees (Invariants)
- Editing the recipient on resend never mutates the master order record

Sample 03→04 — PR 本文に載る確認者の判定Verifier table in PR body

  • AC 1AC 1前回の送り先が入るPre-fills last recipient address

    TestResendPrefillsLastAddress

    PASS
  • AC 2AC 2前回が無ければ空のままLeaves blank when no history

    TestResendWithoutHistoryLeavesBlank

    PASS
  • 保証Guarantee注文マスタの記録は書き換えないMaster order record is unchanged

    TestResendKeepsAddressHistory

    PASS

Architecture & Guards

この型を支える設計判断とガードArchitectural decisions and mechanical guards

Agent Architecture役割ごとにエージェントを分けないDo not split agents by role

  • 実装は1セッション通し:Single session for implementation: 役割ごとに分けると、受け渡しのたびに「なぜそうしたか」が落ちる。Splitting by role drops the "why" at every handoff.
  • 文脈を切る理由がある所だけ subagent:Subagents only when isolation matters: 確認者の判定・画面操作の重い出力・並行の読み合わせだけに限定する。Used only for verifier judgment, heavy UI operator output, and parallel spec checks.

Mechanical Guards守らせる規則はプロンプトではなく Hook で止めるEnforce rules with Hooks, not prompts

  • 破壊的・越権操作の遮断(guards):Block destructive actions (guards): main への直接 push、権限のない自動マージ、メイン作業ツリーでの checkout を機械的に止める。Mechanically block direct pushes to main, unauthorized auto-merges, and branch checkouts in the main worktree.
  • 秘密情報の混入防止(secret-guard):Prevent secret leaks (secret-guard): .env や鍵の読み書き・git add を settings.json の deny とフックで遮断する。Block reading, writing, or staging .env and key files via settings.json deny rules and pre-tool hooks.