CODE IN TOKYO

````markdown

Claude Codeで実践する「音声入力 → 論理化 → 実装」の手順

前回、音声入力をそのままAIに投げると危ない、という話を書いた。

音声入力は便利だが、かなり曖昧な言葉が混ざる。

「いい感じに」 「Appleっぽく」 「なんか高級感ある感じで」 「ここは適当に」

こういう言葉をそのままClaude Codeに投げると、Claudeは忖度して実装を始める。

結果として、

ということが起きる。

なので私は、Claude Codeで実装させる前に、必ず一度「論理化」のステップを挟むようにしている。

基本方針

Claude Codeをいきなり実装者として使わない。

まずは、Claude Codeに「参謀役」をやらせる。

流れはこう。

音声入力
↓
Claude Codeに整理させる
↓
実装指示書に変換させる
↓
実装前に確認
↓
実装
↓
レビュー

ポイントは、音声入力の内容をそのまま実装させないこと。

Step 1. 音声入力で雑に投げる

最初は雑でいい。

例えばこう話す。

メモアプリを作りたい。
ObsidianっぽくローカルのMarkdownを扱いたい。
画面は黒系で、Appleっぽい高級感がある感じ。
左にフォルダ、真ん中にメモ一覧、右に本文。
タグも使いたい。
検索もほしい。
とりあえずReactで作って。

このまま実装させてはいけない。

この中には曖昧な言葉が多い。

Obsidianっぽく
Appleっぽい
高級感
とりあえず

ここをClaudeに勝手に解釈させるとズレる。

Step 2. まずClaude Codeに「論理化」させる

Claude Codeには、最初にこう指示する。

まだ実装しないでください。

今の私の指示は音声入力なので、曖昧な表現が含まれています。
まず内容を論理化してください。

以下の形式で整理してください。

1. 目的
2. 実装対象
3. 機能要件
4. UI要件
5. 技術要件
6. 曖昧な表現
7. 確認が必要な点
8. 実装前に決めるべきこと

この段階ではコードを書かないでください。

ここで重要なのは、

まだ実装しないでください

を必ず入れること。

Claude Codeはすぐ実装に入りたがるので、最初に止める。

Step 3. Claude Codeに出させる整理結果

Claude Codeには、例えばこう整理させる。

1. 目的
Markdownベースのメモ管理アプリを作る。

2. 実装対象
React製のフロントエンドアプリ。

3. 機能要件
- Markdownメモの作成
- Markdownメモの編集
- メモ一覧表示
- フォルダ別表示
- タグ付け
- キーワード検索

4. UI要件
- 3カラム構成
  - 左：フォルダ一覧
  - 中央：メモ一覧
  - 右：本文編集エリア
- ダークモード前提
- 余白を広めに取る
- シンプルな見た目にする

5. 技術要件
- React
- TypeScript
- 状態管理はまずuseStateでよい
- 保存先は初期版ではlocalStorage
- 将来的にローカルMarkdownファイル連携を検討

6. 曖昧な表現
- Obsidianっぽい
- Appleっぽい
- 高級感

7. 確認が必要な点
- 実際にローカルファイルを読み書きするのか
- まずはブラウザ内保存でよいのか
- Markdownプレビューが必要か
- タグは複数設定できる必要があるか

8. 実装前に決めるべきこと
- 初期版はlocalStorage保存とする
- Markdownプレビューは後回し
- まずは3カラムUIとCRUDを優先する

ここまで来ると、かなり実装指示に近くなる。

Step 4. 実装指示書に変換させる

次に、Claude Codeへこう指示する。

上記の整理内容をもとに、実装指示書を作成してください。

条件:
- 実装順序を明確にする
- ファイル構成を提示する
- 各ファイルの責務を書く
- 初期実装でやること、やらないことを分ける
- 実装後の確認項目を書く
- まだコードは書かない

このステップで、Claudeに設計書を作らせる。

出力イメージはこう。

## 初期実装スコープ

やること:
- 3カラムレイアウト
- メモ作成
- メモ編集
- メモ削除
- タグ表示
- 検索
- localStorage保存

やらないこと:
- 実ファイルシステム連携
- Obsidian API連携
- Markdownプレビュー
- 認証
- クラウド同期

この「やらないこと」がかなり重要。

AIは気を利かせて余計なものを作りがちなので、スコープ外を明示する。

Step 5. ファイル構成まで決めさせる

次に、実装前にファイル構成を決める。

実装前にファイル構成を提案してください。

条件:
- コンポーネント単位で責務を分ける
- 1ファイルに詰め込みすぎない
- hooksが必要なら分離する
- 型定義は別ファイルにする
- まずは過剰設計にしない

出力例。

src/
  App.tsx
  types/
    memo.ts
  components/
    Layout.tsx
    Sidebar.tsx
    MemoList.tsx
    MemoEditor.tsx
    SearchBox.tsx
    TagList.tsx
  hooks/
    useMemos.ts
  utils/
    storage.ts

責務も書かせる。

App.tsx
- 全体の状態を接続する

useMemos.ts
- メモのCRUD
- localStorageとの同期

storage.ts
- localStorageの読み書き

Sidebar.tsx
- フォルダ一覧を表示

MemoList.tsx
- メモ一覧を表示

MemoEditor.tsx
- 本文編集を担当

ここまで決めてから実装に入る。

Step 6. 実装開始のプロンプト

ここで初めて実装させる。

では実装してください。

条件:
- 先ほど決めたファイル構成に従う
- 初期スコープ以外の機能は実装しない
- 1ファイルに責務を詰め込みすぎない
- TypeScriptの型を明確にする
- 実装後に、変更したファイル一覧と確認手順を出す

これで、Claude Codeの暴走がかなり減る。

Step 7. 実装後にレビューさせる

実装が終わったら、すぐに次の指示を出す。

実装内容をレビューしてください。

観点:
- 初期スコープ以外のことをしていないか
- 1ファイルに責務が集中していないか
- 型定義が曖昧ではないか
- localStorage処理がコンポーネントに漏れていないか
- UI要件を満たしているか
- 不要な複雑化がないか

問題があれば、修正案を出してください。
まだ修正はしないでください。

ここでも、

まだ修正はしないでください

を入れる。

レビューと修正を同時にやらせると、勝手に直し始めて変更範囲が広がることがある。

Step 8. 修正指示を出す

レビュー結果を見て、必要なものだけ修正させる。

以下の指摘だけ修正してください。

- useMemos.tsにlocalStorage処理が直接入りすぎているのでstorage.tsへ分離する
- MemoEditor.tsxが大きくなっているので、タイトル入力と本文入力を小さなコンポーネントに分ける

それ以外の修正はしないでください。
修正後に変更ファイル一覧を出してください。

ポイントは、

それ以外の修正はしないでください

を入れること。

AIは「ついでに良くしておきました」をやりがちだが、これは危ない。

私がよく使うテンプレ

最後に、実際によく使うテンプレを置いておく。

まだ実装しないでください。

これは音声入力で作った雑な指示です。
まず内容を論理化してください。

以下の形式で整理してください。

1. 目的
2. 実装対象
3. 機能要件
4. UI要件
5. 技術要件
6. 曖昧な表現
7. 確認が必要な点
8. 初期スコープ
9. スコープ外
10. 実装順序

その後、私が確認するまでコードは変更しないでください。

実装に入るときはこれ。

上記の内容で実装してください。

条件:
- 初期スコープだけ実装する
- スコープ外の機能は実装しない
- ファイル構成を先に提示する
- 責務分離を意識する
- TypeScriptの型を明確にする
- 実装後に変更ファイル一覧を出す
- 実装後に確認手順を出す

レビューはこれ。

実装内容をレビューしてください。

観点:
- 指示されたスコープを超えていないか
- 責務分離できているか
- 型が曖昧ではないか
- 不要な複雑化がないか
- 将来の拡張に最低限耐えられるか
- 逆に過剰設計になっていないか

まだ修正はしないでください。
まず問題点だけ列挙してください。

まとめ

Claude Codeはかなり強い。

ただし、雑な音声入力をそのまま渡すと、Claudeは忖度して実装してしまう。

だから、

音声入力
↓
論理化
↓
実装指示書
↓
実装
↓
レビュー

という流れにする。

これは少し面倒に見えるが、後戻りがかなり減る。

AI開発では、実装速度そのものよりも、

間違った方向に速く進まないこと

の方が大事だと思っている。