Zenn
🗂

Claude Codeが業務に関わる人間のように推測できるようにする

に公開
Claude
Claude Code
idea

ゴール

Claude Codeが業務知識・業務キーワード盛りだくさんなIssueを理解できるようにする。

丁度いいサンプル課題があったので、これを例にする。

BAについて、下記のご対応をいただけますと幸いです。

・AA/AB/ACと同様に、入荷管理画面( /admin/arrival/ )で【BA：UN】と【BA：カ】に分ける
・BAのラベル印刷時、カバーがセット内容にある商品は、ラベルを2枚出す

こういう依頼がテキストで来る。
普段はもっと説明があるのだが、たまたまキーワードだらけの課題があったので、それを例にする。

よく使う指示

保存されていない記憶を教えて

「キーワード」について、記憶の中だけの情報で説明して

「キーワード」の情報はどこを参照した？

文書化と読み取り

これは業務に関わっている人間が読むとすぐに理解することができる。
実際にこういうIssueが書かれるということは、人同士だと普通に通じる内容で、細かく説明するよりもむしろキーワードを並べた方が理解しやすいということだ。

Claude Code は当然そこまでの推測はできない上に、想像のまま実装を開始してしまう。

これに対して

  • 情報をドキュメントに整理する
  • ドキュメントを正確に読み取れる指示の方法

この二点でClaude Codeが人間と同レベルの理解度になれるようにする。

知識の蓄え方

DBやコードからの調査を依頼する

コアとなる箇所のデータベースの構造を完全に理解してもらう。

最初に示した例の場合は、商品のデータについてDBを調べてもらう。
ここで、人間が「AAとは○○のことで、ABとは○○のことで〜」と教えたり、自分で database-product.md を書いたりしてはいけない。
人間も（Claude Code と同様に）間違ったり不十分だったりする。Claude Code は人間の指示は正しいものとして受け取るので、もしズレていたりエッジケースが漏れていたりすると、それ以降の会話に少しずつズレが出てくる。

Claude Code に調べてもらうには

DBのcategoryテーブルのcategory_codeとproductテーブルのproduct_codeについて、いくつかサンプルデータを取得して調べて。

のようにAA/ABが入っているカラムやグループを関連付けて取得させる。
取っ掛かりが分かれば推測してもっと詳しく調べてくれる。

product, size, color, category のテーブルを調べて

と商品関連テーブル全てを調べてもらったり

/product/detail/123 の画面を表示するときのフローを詳しく調べて

というような画面からコードを調べたりもやってもらい、多角的に商品データをどう扱っているか知ってもらう。

「重要な発見がありました！」などと言ってくるので、まとめてmdファイルに書いてもらう。

加えて、UNIQUE制約やCHECK制約を調べてもらう。ビジネスロジックがそのままルールになっていて解釈ミスが起きないので、DB制約があればあるほど理解が進む。

Claude Codeの理解度チェックをする

最初の課題の意味を説明してもらう。
内容が怪しいなら

「AA/AB/AC」とは何？記憶の中だけの情報で教えて。

課題の各キーワードについて記憶の中だけの情報で説明して

と小分けに聞いて理解が不十分なところを突き止めて、調べ直してもらう。
「説明して」だけだと新たに調査を始めることが多いので「記憶の中だけの情報で」と制限する。

次に、新規セッションを立ち上げる。（これまで使っていたセッションは閉じない。）
先程書いたドキュメントを読み込んで、調査したコンテキストが無い状態でも課題が理解できるかチェックする。

こうすることで、この課題に対するドキュメントの有効性がチェックできる。
勘違いをしている箇所は追加で調査し、ドキュメントを更新する。そしてまた新規セッションで理解度チェックをする。（このとき調査するのは、最初で調査した方の古いセッションで調べる。）

  1. 課題に関係するDBやコードを調査する
  2. 調査した結果をドキュメントに記述する
  3. 新規セッションでドキュメントを読んで理解度チェックをする

この繰り返しで、Claude Codeが人間と同じような理解度になったら完了だ。

ドキュメントを読むための指示の方法

新規セッションでドキュメントを読むときに、単純な指示だと流し読みされてしまって折角書いていることをちゃんと読まないことが多い。

Claude Code には専用コマンドを作れる仕組みがあるので、それを利用して課題解決用の準備コマンドを用意した。

.claude/commands/prepare.md
# 課題解決の準備 {課題番号}

以下のTodoリストを作り、表示して。
Todoリストを順に実行しながら課題の説明書を作成して。

※「ドキュメント」は CLAUDE.md と ./claude-docs/ ディレクトリにある文書のこと。

1. ** CLAUDE.md 再読込 ** 
  - CLAUDE.mdを読む。
2. ** 課題の読み込み **
  - claude-docs/current-work/ に $ARGUMENTS から始まるディレクトリがあるので、それを「課題ディレクトリ」とする。なければユーザーに問い合わせる。
3. ** 課題の解析**
  - {課題ディレクトリ}/issue.md に課題が書いているので、このプログラムを実装するための情報を詳しく調査する。以下の順に実行する。
    1. コードを読む前に、まずclaude-docsにある関連するドキュメントを読む。
      - 関連ドキュメントはしっかり読む。
      - ** 分からないキーワードがあれば、ドキュメントから探すこと **
      - ** ドキュメントを探しても分からないキーワードは、コードを探す前にユーザーに問い合わせること **
    2. 課題に必要なコードを読む。
    3. もし必要ならDBに接続して解析する。
      - DB情報は詳しくドキュメント化されているので、ドキュメントで分からないことがある場合のみDBに接続する。
    4. もし不明瞭なことがあるならユーザーに尋ねる。
4. ** 解析結果のまとめ **
  - 実装する方法を「claude-coding-rules.md」に従って深く考える。
5. ** 解析結果のドキュメント作成 **
  - 次の２つのファイルを作成する。
    1. 理解した内容を含めてClaudeの解釈を付け加えた課題の内容を「{課題ディレクトリ}/issue-claude.md」に書く。
      - 「現状」・「問題点」・「思いついた他の解決方法」など、おすすめの分かりやすい文章で。
    2.  実装内容を「claude-document-rules.md」に従って「{課題ディレクトリ}/instructions.md」に書く。実装コードは書かない。

Claude Code はよく勝手に実装を始めるので、それを止めるための指示を各所に入れている。

  1. ドキュメントを読む
  2. コードを読む
  3. DBを調査する

という順番を守るようにしつこく書いた。

最初に挙げた課題をそのまま claude-docs/current-work/issue-123-BA-label/issue.md にコピペして、Claude Codeコンソールから/project:prepare issue-123 のようにすると、prepare.mdに従って実行してくれる。

結果は２つのファイルに保存してもらう。

issue-claude.mdはClaude Codeの理解度チェックに使う。
instructions.mdは今後の実装で利用する。もし実装中にClaude Codeが何か勘違いをしていたら、このファイルを読み直してもらうと軌道修正ができる。

結果

実際にこの手順でやってみると、最終的には人間以上に理解してエッジケースまで考慮されていた。
あんなに抜けていたClaude Codeが完全に理解してくれてびっくりしたのでこの記事を書いた。
※ 課題を書いた人はシステム利用者であり内側のことに詳しくないので、細かな仕様漏れは実際によくある。

ちなみに、今のプロジェクトでのClaude Code用ドキュメントは1万行を超えた。

Discussion