ぼくというコンテキストを開発ガイドラインで明文化する with Claude Code

Claude Codeでいろいろコードを書いてもらってるけど、
割と好みじゃない感じになって負債が溜まりがちに。。。

ぼくが好きな原則・アーキテクチャ・テスト方針などを、
ちゃんと伝えるためのドキュメントが必要性が高まってきたので、
Claude Codeと一緒に整理しているときの備忘録(*´ω｀*)

0->1の想定で、サンプルコードがほぼないアプリを作りたい感じ

コンテキストエンジニアリング

着想としては、このあたり。コンテキスト(文脈)を伝えて、LLMの解空間を絞りたい。
けど、コンテキストが暗黙知化してるので、まずは明文化が必要

連動させたり、ツールを作ったりするのも便利だけど、結構変化が早いので、
どのエージェントでも利用可能な部分を整えていくことに注力するのがよさそうだと感じてる

コンテキストなしで生成したときの悩み

雑に使っていたときの悩みはこんな感じ

無駄にファイル/クラス/関数を作る(まだ必要ないのに)
無駄にテストを書きすぎる(コードレビューで十分な部分とかも)
変なところにファイルを置く

などなど。。。

都度、指摘して、CLAUDE.mdを増やしていたけど、
無限に出てくるので、まずは土台を整えるところから

用意したもの

おおまかにはこんな感じ

尊重する開発原則(DRY/YAGNI/単一責任の原則などなど)
ブランチ戦略やコミットルール(GitHub FlowやConventional Commitsなど)
開発スタイルや開発の流れ(t-wada推奨のTDDなど)
アーキテクチャ(MVVMなど)
ディレクトリ構成(monorepoとかfeature-firstなど)
例外処理(try-cath方式/Result方式など)
テスト戦略(UT/ITなどでの観点や対象など)

進め方

それぞれでファイルを作成
ざっとドラフトで書いてみる
Claude Codeにレビューしてもらう
手直しする
またレビューしてもらう
...

という感じで繰り返すのがいい感じ

「AIエージェントでの開発で有用か」をメインの観点として、
AIにレビューしてもらい、必要な表現や冗長な表現をリストアップしてもらう

レビューのときは、こんなプロンプトを何度も投げて整えていった

開発ガイドラインを整備しています。

AIエージェント向けに効果的な内容にしたいのですが、 
ベテラン編集者・ベテランエンジニアとして、深くレビューし、
改善案や不明点・懸念点などをリストアップしてください。

リストアップした内容は、計画ファイルを作成し、保存してください
その後、一つ一つ、ユーザと議論し、計画を具体化してください
ultrathink

このプロンプトをベースに、観点などをちょっと変えたりして、取り込みたい改善点が出なくなるまで、何度も繰り返す感じ作ってみた

最初からClaude Codeに作ってもらったけど、
無駄な部分が多いので、レビューも修正も大量で結構つらかった。。。

注意点・気にしたこと

Claude CodeにAIエージェント視点でレビューしてもらった中で、
割といろいろ見えてきた気がする

トークン量に限りがあるので、なるべく簡潔な内容にする

AIが学習済みの内容や一般的な使い方は不要
その中でも守ってほしいポイントだけ記載

コード例は極力減らす

トークン量だけでなく、メンテナンスも大変なので、なるべく減らす
文章から生成できるように内容を精査する

TDDやMVVMなどの用語は、自分の好きな形と合ってるかを確認する

幅が広いことが多いので、AIが理解していることと一致しているか確認する
割とブレが大きいので、人名や守ってほしいポイントを記載する
特にUseCaseとかRepositoryは、いろんなところで使われるので、ブレが大きいので、
「このプロジェクトのUseCaseは〇〇である」のようにしっかり定義しておくとよい

表やラベルなど、構造がわかりやすい形のほうがよいっぽい

同じ比較項目であれば、箇条書きより表のほうがよいっぽい
計画:などのラベルがあるほうがよいっぽい

他のファイルを見つけられるようにしておく

関連ドキュメントへのリンクなどの内部リンクを多めに
ただ、リンク先を読まないこともあるので、大事なことはいろんなとこに書いておく

広い範囲で適用できるようにする

ぽこぽこアプリを作っていきたいので、
最終的には、いろんなリポジトリに組み込めるようにしたい

普段はFlutterとNuxtがメインなので、こんな感じで分類・配置する

_docs/
  # 作ったやつ(submodule)
  _guideline/
    # 言語非依存: 原則やブランチルールなど
    00_proccess/
    # 言語非依存(要拡張): アーキテクチャなど言語に依存する部分の基本方針
    01_architecture/
    # 言語依存: 01_architectureの具体的な実装。Flutter ver
    10_flutter/
    # 言語依存: 01_architectureの具体的な実装。Nuxt ver
    20_nuxt/
  
  # プロジェクト固有: 要件や機能など
  projects/

関係性としては、こんな感じ

開発全般系: projects/ -> 00_process/
実装方針系: projects/ -> 10_flutter/ -> 01_architecture/ -> 00_process/

どこまで共通化・共用できるか、悩ましいけど、
ある程度の方針は使いまわしつつ、言語を増やしていけるような構成で試してみる

実際試してみて、足りないところを取り込んでいって、
ガイドラインをブラッシュアップしていくサイクルの予定

おまけ: Gemini CLIでレビュー

Gemini CLIにも同じプロンプトでレビューさせてみたけど、
あまりよい指摘が出てこなかったので、Claude Codeだけで実施

ChatGPT o3とかよさそうなので、試してみても良かったかもしれない。。。

おまけ2: 名書・原書をちゃんと読もう

Claude Codeを使えば使うほど、設計力やレビュー力が足りないな。。。
と思い、いろいろ本を読む時間が増えがち

最近は、このあたりの本を読んだり、読み直したり

TDD/DDD/CleanArchitectureなど、乖離しがちなので、
名書・原書をちゃんと読もうという気持ちが高まってる

おわりに

ちゃんと整えているプロジェクトだと、すぐにAIを活用できるけど、
ゆるくやっているので、まずはしっかりとした基礎固めから。。。

とりあえず、初版のドキュメントができたので、
実際に適用しつつ、足りなそうなところを補強していこう(*´ω｀*)!!

くらげになりたい。

くらげのようにふわふわ生きたい日曜プログラマなブログ。趣味の備忘録です。