Claude Codeをコーチにして、アーキテクチャを学び直す
こんにちは。リテールアプリ共創部のYahiroです。
昨今、私の所属するチームをはじめ部内では、コンテキストをどう貯めるかといった部分で様々な施策が日々生まれています。
私は普段、Flutterアプリ開発を主に行っておりますが、Flutterアプリ向けのコンテキストを同僚が書き、それをレビューするにあたって一つの悩みが生まれました。
あれ……Clean Architectureだとこのディレクトリ構成が正解なんだっけ・・・？
ここでfactory使うんだったっけ・・・？
などなど、同僚が作成してくれたコンテキストに対して、正しい見解でレビューできているか不安になる瞬間がありました。
AIの発達とともに、コードの生成時間は飛躍的に縮んだ一方で、手でコードを書く機会が減り、細かい書き方に対する知識が朧げになっている部分もあるかなと思いました。
これは一度しっかり学び直す必要があるぞ、と思い立ったため、今回は、Claude Codeをコーチにして、アーキテクチャを学び直したアプローチをご紹介します。
全体像
今回の手法は、端的にいうと、Claude Codeにアーキテクチャのコンテキストと要件を渡して、教材を作ってもらった後に手で実装していくというものです。
人間の技術者とそれを行う場合、コーチになるエンジニアの時間をかなり拘束してしまいますが、Claude Codeを用いることにより、いつでも何度でも聞き返せるコーチを得つつ、わかるまで手で実装することができます。
以下のような順番で進めていきます。
- OpenSpecで要件のコンテキストを作成する
- Claude Codeに各種ドキュメントと環境を整えてもらう
- 実装
- 復習
順に見ていきましょう。
事前準備
学習を進めるにあたって、以下の二つを用意してください。
OpenSpecのインストール
開発を行う環境にOpenSpecを導入しておいてください。
学習を始めるプロジェクトの準備
学習を始めるにあたって、既存のプロジェクトに機能を追加する形にすると始めやすいです。
新規作成でも大丈夫なので、学習に使えるプロジェクトを用意しておいてください。
私は、Flutterアプリの既存プロジェクトで行いました。
1. OpenSpecで要件のコンテキストを作成する
まず、作る機能のコンテキストを整えていきます。
今回は仕様駆動開発、OpenSpecを採用して進めていきます。OpenSpecが必須ではないので、他のフレームワークを使用していただいても問題ありません。
仕様を先に詰める目的は、機能の開発を行うわけではなく、機能開発を通してアーキテクチャを学ぶための土台を作ることです。
ですので、あまり細かい仕様は必要ありません。
まず、今回学習を行うプロジェクトの中で以下を実行します。
openspec init
これにより、OpenSpecのディレクトリ、ファイルが自動生成されます。
これで、OpenSpecのスキルが使えるようになったので早速要件を作成していきましょう。
以下を実行して、OpenSpecで仕様を作成します。
/openspec-propose ＜仕様のメモ、テキストなど＞
上記コマンドの第一引数には、学習を進めるにあたって作りたい機能の仕様をテキストでそのまま貼るか、mdなどにまとめたもののファイルパスを渡してください。
生成が完了したら、中身を確認して微調整してください。
ポイントは、ここで実装の詳細まで詰めすぎないことです。
OpenSpecでproposeを実行した場合、既存のコードを確認して、それに沿ったクラス実装などまで計画に起こしてくれますが、今回それらを学習することが目的なので、そこまで仕様策定の段階では不要です。
作成が終わったら、いよいよClaude Codeで学習環境の整理を進めていきましょう。
2. Claude Codeに各種ドキュメントと環境を整えてもらう
いよいよ学習環境を整えていきます。
渡すプロンプトのポイントは4つです。
-
要件について
要件については、先のOpenSpecで作成しているのでそれを渡すようにしましょう。 -
ベースとなるコンテキスト
以下のプロンプトでは、<参照ドキュメント>としています。環境や学習したいアーキテクチャによって適宜差し替えてください。 -
既存コードとの接続（オプション）
私の場合、すでに開発をある程度行なったプロジェクトをベースに学習を進めました。
そのため、以下のプロンプトには既存コードの整理と接続についての記載がありますが、新規で作成したプロジェクトで試す場合は不要なので削除してください。 -
自分の状況（知見、経験値など）
最後に自分自身についてです。私は、アーキテクチャについて一から学び直すため、初学者として記述しました。
以下のプロンプトでの記載は、Flutterの公式アーキテクチャを学ぶ前提となっています。
ご自身の学びたいレベルや、スキルに応じて記載をチューニングしてもらえたら良いと思います。
プロンプト
OpenSpec の <change-name> を実装したい。実装にあたっては <参照ドキュメント>に
則ったアーキテクチャで進めたい。
既存の実装は別の設計パターンで作られているが、これらは塩漬けにして、
新しいコードは別のディレクトリを切って書きたい。
まず、既存のコードを lib/legacy/ のようなディレクトリにまとめてください。
次に、私は Flutter は最低限書けるものの、オブジェクト指向の SOLID や
Flutter 公式ガイドのアーキテクチャについて知見がない初学者である。これらを実装しながら学びたいので、AI 主導の実装ではなく、
私がコードを手で書いて理解できるように、最低限以下が用意された状態にしてほしい:
README.md— この機能が何のためにあって、どの md からどの順番で読めばよいかの案内ARCHITECTURE.md— どこに何を置くか・依存方向のルールなどアーキテクチャの全体像CHECKLIST.md— 実装をどの順番で進めればよいかが分かる、チェックボックス形式の手順- 各レイヤに、責務とやってよいこと／NG が冒頭コメントで書かれた空の雛形ファイル
また、既存の実装から呼び出さなければならないデータや機能がある場合、
既存コードには極力触らずに、抽象化などといったオブジェクト指向や SOLID、
Flutter 公式ガイドのアーキテクチャに沿って外から使える形での改修も併せて
やってほしい。
上記を実行した後、README.mdやARCHITECTURE.mdをまずは読み、これから何を行うかをざっくり頭に入れましょう。
ここでのポイントは、全てを完全に理解しようとすることではなく、生成されたmdを上から下まで眺めて一通り読み切ることです。
実装を始める前に、一通り読み切っておくことで、次の実装で全体像を意識しながら書けるのでより効果的に学習することができます。
3. 実装
準備が整いました。あとは実装していきましょう。
着手する時は、Claude Codeに何から手をつけたらいいかを聞いてみてください。Claude CodeはCHECKLIST.mdを読んで、対応してくれます。
ここでのポイントは4つです。
-
わかるまで聞く
読んで字の如くですが、わかるまで聞くのがポイントです。人間に何回も聞くのはできないことが多いですが、AIにはいくら聞いてもいいので、わかるまで聞きましょう。腹落ちしたタイミングでコードを書き始めるとより効果的かなと思いました。 -
新しい概念がない時はAIに書いてもらう
機能がある程度大きい場合、次に書くクラスで新しい学習概念がない時があります。そういう時は、AIに書いてもらいましょう。復習として複数回書くのも効果的ですが、時短のため、適宜AIに書いてもらうと良いです。 -
コードサジェスト機能は使いすぎない
GitHub Copilotなどのコードサジェスト機能は非常に便利ですが、オンにしたまま着手すると、ほぼ正解を出してきます。
学習効果がないわけではありませんが、ずっとオンにしていると写経になってしまうので、適宜使うようにしましょう。 -
元となったドキュメントも適宜確認する
Claude Codeで作成されたドキュメントは、AIで作成されたものである以上ハルシネーションを起こしている可能性もあります。適宜元となったドキュメントを確認するようにしましょう。
4. 復習
実装お疲れ様でした。
ここまで手で書いてきた方は、ある程度自分の設定したアーキテクチャに対して理解が深まっていると思います。
忘れないうちに、Claude Codeに復習ドキュメントを作ってもらって、読むようにすると良いです。
私は以下のようなプロンプトでClaude Codeに作成してもらいました。
プロンプト
<change-name> の実装が一段落ついたので、このブランチを通じて学んだことを
あとで振り返れる形で md にまとめてほしい。
出力先は lib/features/<feature-name>/learnings.md。
私は初学者で、この実装は学習の場でもあった。なのでこのドキュメントは
「思い出すためのノート」として、後日同じパターンを別の feature に適用する
ときに開ける形にしてほしい。
内容はブランチで実際に起きたこと（コミット履歴、CHECKLIST.md のチェック履歴、
新規追加ファイルとその冒頭コメント、テストコード、エラーログ）から拾うこと。
創作で内容を盛らない。手元で確認できない事柄は書かない。
書く前に README.md / ARCHITECTURE.md / CHECKLIST.md を必ず
読み、これらと矛盾しないようにすること。
ここで作成されるmdを再度上からざっと読んで、自分が書いたコードを読み返すと理解が深まります。
まとめ
私は昔から、勉強する時はノートに一回書くタイプでした。
私自身、昨今のAIの台頭によりコード生成スピードは上がったものの、手でコードを書くタイミングが少なくなってきていました。
そこで、AIを使って自分でコードを書くことにより理解を進めてからAIを使ったコーディングを行うことで、全体的に自分自身の理解、そして成果物の精度が上がったと感じています。
技術は日々新しいものが出てきて、便利な一方、しっかりと基礎を適宜勉強しながら使いこなしていきたいなと考えています。
今回は、再学習として行いましたが、新技術のキャッチアップにもClaude Codeをコーチとした手法は応用できそうなので試していきたいです。
