VSCode+Claude Codeで業務コードの8割をAIに書かせています。試行錯誤で掴んだコツを共有します。

事前準備が9割

CLAUDE.mdでプロジェクト情報を整理

/initコマンドでプロジェクトの全体像を記載させる。

アーキテクチャ・フレームワーク
アプリの概要
テスト・lintのコマンド

アーキテクチャとかフレームワークは地味に重要で、これがあるといちいち調べさせなくてもよくなるし、トークンの節約になる。

明らかに察しが良くなるので必ずやる。

さらに、個別のタスク遂行フローを追記していく。


...Claudeが自動で書いた部分

## タスクの遂行方法

適用条件: 実装を依頼された時。単なる質問事項の場合適用されない。

### 基本フロー

- PRD の各項目を「Plan → Imp → Debug → Doc」サイクルで処理する  
- irreversible / high-risk 操作（削除・本番 DB 変更・外部 API 決定）は必ず停止する

#### Plan

- PRDを受け取ったら、PRDを確認し、不明点がないか確認する
- その後、PRD の各項目を Planに落とし込む
  - Planは `.docs/todo/${タスクの概要}.md` に保存
- ユーザーにPlanの確認を行い、承認されるまで次のフェーズには移行しない

#### Imp

- Planをもとに実装する

#### Debug

- 指定のテストがあればテストを行う
- 指定がなければ関連のテストを探してテストを行う
- 関連のテストがなければ停止して、なんのテストを行うべきかユーザーに確認する
- テストが通ったらフォーマッタをかける

#### Doc

- 実装を`.docs/design/${タスクの概要}.md` に保存
- ユーザーからのフィードバックを待つ。フィードバックがあれば適宜前のフェーズに戻ること

テストコマンドを明記し、テストを自分でやれる状態にしておく。これでClaude Codeの自律力がアップする
フローを明確にし、停止条件も書く。ただ、Planは shift+tab2回押しで専用モードが追加された模様。こっちを使ったほうが良い

PRDで要件を明確化

PRDファイルを作成する。具体的な内容は下記。

やりたいこと・目的
関連ファイル・ディレクトリ
モデル・エンドポイント詳細

自信がなければClaude Codeに「PRD作りたいんだけど。。。」と話しかけ、壁打ちしながら作る。

サンプル:

# 商品マスタ価格情報API

## 目的

検索キーワードをもとに、該当の商品`Product`の一覧とその価格情報`PriceMaster`を取得するAPIを作りたい

## 要件

- 検索キーワードを入れてAPIを叩いたら、該当の商品マスタ一覧が得られる
- 検索キーワードの、検索項目は商品マスタ.商品コードと商品マスタ.商品名の両方をor検索
- 検索キーワードは必須項目。指定がなければ400エラーにする

## 完了条件

下記のテスト実行が成功

path/to/test/test_hoge.py::TestHoge::test_method


## 制約
- エンドポイントは`GET /hoge/product-pricing?search_word=検索キーワード`とする

## 実装ガイダンス (参考情報)
- Viewは`_BaseHogeViewSet`を継承したViewSetクラスを作ること
- ViewSetではfilterset_classを使って検索機能を実現すること

テストの成功を完了条件に書いておく。絶対に書いておく。

テストコードがあるなら最悪要件すらなくても良い。テストを元に要件を勝手に作りはじめる。そのぐらいテストコードが大事。

次の章でテストについて詳しく説明する。

テストを1パスだけ書いておく

ど正常のテストを1つだけ書く。テストがある環境でこそClaude Codeは本領発揮する。

コツ：

アサート部分だけ書いて、テストデータ作成はClaude Codeに任せる(めんどくさいもんね)
完了条件にテスト成功を含める

テストサンプル:

def test_hoge(self):
    """
    ざっくりとしたテストの条件と期待値をここに書く
    """
    
    # TODO: Claudeくん、ここでテストデータ作成してね
    # ...

    response = Client().get("/hoge/product-pricing?search_word=1000")
    self.assertEqual(
        [
            {
                "id": 1,
                "code": "1000",
                "name": "商品名",
                "price_masters": {
                    "value": 100
                }
            }
        ],
        response.json()
    )

assertから逆算し、必要なテストデータを作ってくれる。便利すぎる。

テストがあると難航時もデバッグログを入れて実在のエンジニアのごとく解析する。
逆にテストなしだとimportエラーが起きたものをもってきたり、うっかりしがち。
必ずテストを書くか、既存のテストがあればそれを参考にテストを作らせてから本実装に入る。

実装フロー

下記のプロンプトを打ち、実装を開始させる。

@path/to/prd_file を実装して

Shift+Tab2回でプランモードに入れるとプランがもっと確実になる。

プラン確認・修正

出力されるプランを添削し、納得いくまで修正させる。

自動承認で放置

プランにOKを出したら、Shift+Tabで自動承認モードにして基本放置。テストを駆使して頑張ってくれます。

実装完了

実装完了かつテストが成功すると、lintを実行し、いい感じにしてくれます。

リファクタ

実装後、適宜リファクタを依頼する。ドメインモデル化とか、サービス層切り出しなど、プロジェクト固有のアーキを反映させる。また出来上がったコードを参考に、残りのテストケースも書かせる。カバレッジ100%になるように様々なテストケースを書いてくれる。

設計書生成

最後に設計書を逆出力させる。追加開発時のコンテキストとして再利用する。commitの必要はないのでgitignoreしてる

覚えておくと便利な操作

@ファイル名 ファイル参照
Shift+Tab 自動承認モード
Shift+Tab2回 Planモード。壁打ちしながらPlanをブラッシュアップしていく
Esc 処理停止
Esc×2 特定の会話まで戻ってプロンプト書き直し
Cmd+E/A 行末/行頭移動
VSCodeでコード選択すると→プロンプトに自動入力される。Cursorにもあったやつ。便利
claude --resumeで今までの会話履歴閲覧/呼び出し
think``think hard``ultrathink プロンプトにいれると拡張思考モードになる。基本thinkを常用、気合がいりそうなときはultrathinkをしてる

下記動画がかなり参考になる

感想

基本的にAnthropic社のベストプラクティス通りにやっただけ。

Claude Codeはマジで粘り強くあらゆるコマンドを使ってコードベースを調査する。調査内容がブワーッと出てくるのだけど、「あ〜そうだよね、そこ調べるよね。あれ？そこも調べるの？あれ、ナニソレ？何やってんの？え、すげえ理解してる怖」ってなった。CursorやWindsurf、RooCodeあたりとの違いはその粘り。この調べ方は本物のエンジニアとほぼ同等だと思う。

その代わり、トークンの消費が激しいので、MAXプランでないとすぐに嫌になってしまうと思う。重要なので2回言うけど、MAXプランでないとすぐに嫌になる。MAXプランで定額で好き放題調査させられることに意味がある。

また、DDDなどドメイン駆動開発的なコードを一発で書くのは難しそう。
既存実装などを参考として見せつつ(勝手に見るけど)、動くものを書いてもらい、テストグリーンを維持しながら2~3回修正させて完成させるアプローチをよく取る。

ただ察しは異常に良いので、チームのアーキテクチャやドメイン知識をきちんとインプットすれば、もっと高度なことができそう。

おまけ使ってるMCP

github...プルリクのレビュー指摘のリンクとかを貼ると勝手に指摘対応する
mcp-atrassian...JIRAのチケットリンクから作業開始できる。あんまいらない
puppeteer...フロント開発の際、勝手にローカル環境のブラウザ開いてテストするので便利
sequential-thinking...難しい問題を構造的に思考してくれるやつ。効果の程は分からないがたまに勝手に起動してる