3
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

Claude Codeに毎回同じ説明をしていませんか?仕様の手戻りを減らすCLAUDE.mdとタスク設計

3
Posted at

「Claude Codeに毎回同じ説明をしている」「コードは直ったのに、依頼した人から『これじゃない』と言われた」。AIを使った開発で、こんな手戻りはありませんか?

たとえば「登録を増やしたいから、LPを改善して」と頼むケース。ボタンの色や文言を変えることはできます。でも、本来知りたいのは登録した人が増えたか。ここが共有されていないと、見た目が変わっても成果は判断できません。

結論から言うと、毎回の長いプロンプトより、変わらない判断基準と今回だけの依頼を分けて残すのが有効です。Claude Codeなら、プロジェクトの共通ルールを CLAUDE.md に、施策ごとの条件を別のMarkdownファイルに置けます。

この記事では、マーケ担当とエンジニアが一緒に進める「登録フォーム改善」を例に、コピーして試せる形まで整理します。※以下のサービス・数値・ファイル名は説明用の架空例です。

まず、「作業」と「成果」を分ける

依頼としてよくある表現 AIが作業として受け取りやすいこと 本当に確認すべきこと
登録ボタンを目立たせたい 色・大きさを変更 ボタン押下後の登録完了が増えたか
フォームを簡単にしたい 入力欄を減らす 入力完了率と登録品質が落ちていないか
コンバージョンを計測したい クリックイベントを追加 登録成功時に1回だけ計測されているか

「画面の変更」は納品物、「登録完了」は成果です。後者まで言葉にしないと、AIも人も達成基準を勘違いしやすくなります。

1. CLAUDE.md には、変わらないルールだけを書く

リポジトリのルートに CLAUDE.md を置きます。長い社史や議事録を入れる必要はありません。プロジェクトで繰り返し守る判断基準だけに絞ります。

CLAUDE.md
# このプロジェクトの開発ルール

## 誰のためのサービスか
- 対象:プログラミング学習を始めたい社会人
- ユーザーは専門用語に不慣れな前提でUI文言を考える

## 何を成果とみなすか
- 最優先の成果:サーバーで登録が成功した件数
- ボタンクリック数だけを登録数として報告しない
- 登録が失敗したときは成功イベントを送信しない

## 実装時に守ること
- 既存のコンポーネントと計測ルールを最初に調べる
- メールアドレスなどの個人情報を計測イベントに含めない
- 変更した画面の正常系・異常系を確認する
- 不明な仕様は推測で確定せず、質問・保留事項として示す

## 完了報告の形式
- 変更内容/確認した動作/未確認事項/成果の測定方法を報告する

ポイントは、「登録完了」と「クリック」は違うと明記したこと。ここに「今回のボタンを青色にする」のような一時的な指示を足し続けると、すぐに陳腐化します。

CLAUDE.md は指示を引き継ぐためのファイルであり、過去の会話や最新のアクセス解析を自動保存する仕組みではありません。変わる数字は別途更新する必要があります。

2. 今回の施策は、別ファイルで「仮説→変更→検証」にする

たとえば docs/tasks/signup-lp.md に、実行する仕事だけを書きます。

docs/tasks/signup-lp.md
# タスク:登録フォームへの導線改善

## 仮説
ファーストビューに学習内容の具体例がないため、
登録前にサービスの価値が伝わっていない可能性がある。

## 変更範囲
- トップページのファーストビュー
- 登録フォームへの導線文言
- API・課金・認証処理は変更しない

## 現状(仮の例)
- 訪問:1,000セッション
- 登録完了:60件(登録率6%)
- 計測期間:直近7日間

## 完了条件
- スマートフォンとPCで表示崩れがない
- 登録成功・失敗時のUI動作を確認する
- 登録成功の計測が1回だけ記録される
- 変更内容と、公開後に比較する指標を一覧化する

## 公開後の判定
- 同じ定義の登録完了率を比較する
- 流入元・端末の構成差も確認する
- サンプルが少ない場合、改善を断定しない

数字は「仮説の根拠」と「検証の基準」に分けて扱うのがコツです。6%から7%になったとしても、訪問者数や流入構成が違えば、すぐに施策の効果と断定できません。

3. Claude Codeへの依頼は、短く・検証可能にする

両方のファイルがあれば、実際の依頼は次の程度でも意図が伝わりやすくなります。

CLAUDE.md と docs/tasks/signup-lp.md を読んでください。
まず既存画面・登録処理・計測処理を確認し、
今回の変更範囲と不明点を3点以内に整理してください。

その後、変更範囲だけを実装し、関連テストを実行してください。
完了報告には次を含めてください。
1. 変更したファイルと意図
2. 成功・失敗それぞれの確認結果
3. 計測が正しいと言える根拠
4. 未確認事項と公開後に見る指標

AIに「登録率を上げて」とだけ指示しても、未来の数値は保証できません。AIが担当できるのは、改善仮説を実装し、正しく測れる状態を作るところまでです。実際の効果は公開後のデータで判断します。

4. 「できた」報告で見るべき4項目

レビューでは、コードの行数より次を見ます。

  • 意図との一致:変更内容はユーザーの迷いを減らす仮説に沿っているか
  • 正常系:登録成功で完了画面へ進み、正しく計測されるか
  • 異常系:登録失敗や通信エラーを、成功として扱っていないか
  • 判断可能性:改善前後を同じ指標で比べられるか

これは開発の仕事をマーケ側に押し付ける話ではありません。マーケ担当が**「何を成功とみなすか」を定義し、エンジニアが「その成功をどう安全に実装・検証するか」**を設計する、という役割分担です。

よくある失敗

CLAUDE.md に何でも書く:過去の施策・古い数値が混ざると、判断基準がぶれます。長期ルールと今回の依頼は分けましょう。

「テスト通過=施策成功」とみなす:テストは仕様どおり動くことの確認です。マーケティング上の効果は別に測ります。

クリック数を登録数として扱う:登録APIが失敗してもクリックは増えます。成果指標の定義を先に合わせましょう。

まとめ

AI開発で本当に節約したいのは、プロンプトを入力する数分ではなく、認識違いによる手戻りと、成果を判断できない時間です。

  1. 変わらないルールは CLAUDE.md
  2. 変わる仮説・数値・変更範囲はタスクファイル
  3. 実装の完了と、ビジネス成果の達成を分けて判断する

この3つをそろえるだけでも、「AIは仕事をしたのに、何が良くなったか分からない」を減らせます。


関連リンク

学びながら実際に作りたい方へ:AIと対話しながらスキル習得を進めるCodeNestも運営しています。まずはこの記事のテンプレートを、自分のプロジェクトに合わせて試してみてください。

3
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
3
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?