Claude Code Maniacs

Claude Codeとしたのは主に使っている製品だからで、ある程度はCoding Agent全般に適用可能な話だと思う。

Coding Agentの振る舞いについて、比喩的（擬人的）な言い回しが出るのはもうしょうがないね。だってそう見えるから。

以下、これまで調べたりしたことをつらつら書いていく。そんな記事がManiacsを冠していていいのか。

「開発者はあるべき仕様（あるいは行われるべき操作・変更）をClaude Codeに対して宣言し、Claude Codeはそれを実現するために動く」というメンタルモデルを中心にして、どうしても技術的・情報環境的にClaude Codeが躓くようなときに、命令的な追加指示を行う。これが基本となる取り組み方だと思う。

その上で（多くの技術者が既に言及しているはずだが）、宣言した仕様に到達したことを自己検証できるような完了の定義・評価関数ないしはさらに拡張的な何かを与えることで、誤り訂正的に自律駆動させてゆくのが2026年現在の開発者のすべきこと、と認識している。

昨今のClaude Codeの振る舞いを見ている限り、「認知資源が潤沢でさえあれば、シニアエンジニアを凌駕する技術提案・意思決定」すら可能なように思えてきている。ただし、この「認知資源が潤沢でさえあれば」の実現には結構なコストが要る。

常にコンテキスト量管理が行われ、必要な情報を必要なだけ得ている（無駄情報でコンテキスト圧迫されない、lost in the middleが起こるようなコンテキスト肥大化の発生頻度が最小化されている）

実行時に起きている物事を直接見るのに近い形で観察できる（Playwright MCP、リアルタイムログ…etc）

扱っている技術領域に関して信頼できる情報源に即時アクセスできる

ただ、これらは結局のところAnthropicの継続的改善である程度はどうにかなる。

過剰投資しない範囲でエンジニアが上記を満たすようにプロジェクト・開発環境をメンテナンスするのが肝要。

彼らに求めるのは「支払っている数万円を余裕でペイできるパフォーマンス」であり、これは素で使っているだけでも満たせるわけだから、どこまで手を出すかは体制次第。

ローカル開発環境のログはいますぐファイル化するべき。「起動コマンドを打ったシェルの標準出力を取りに行く」は地味に面倒な指示であり、Agentもあたり自発行動もしない（また、デフォルトのまま使っていると、ログの類はユーザーに取りに行かせる発想によりがちなので内部実装でそういう提案行動をさせるようになっているかもしれない）。

ログになっていれば、その所在をデフォルトコンテキストに含めるだけで話が済む場面が増える（CLAUDE.md的なるものに書いておこう）

Coding Agentを利用した並行開発には幾らかのレベルがあるが、主要なものは

同一タスク内のタスクをサブエージェント等で振り分ける

git worktreeを利用する

ローカル開発環境自体を複数作る

といったものだろう。筆者はいずれも使うことがあるが、最も効用を感じたのは（身も蓋もない話だが）環境自体の複数化だ。動作確認系も並行できるのが大きい。Playwright MCPを用いたClaude Code自身によるフロントエンド調査も並行できる点で、git worktree + 環境起動制御よりも自由度が高い。

デメリットは複数環境分の環境追従（依存関係の更新等）だが、これは今日日ほぼ自動化できる。

CLAUDE.mdにはだいたい以下が書かれてあれば、あとはRAG、RAGするのみである

絶対に忘れてほしくないタスク遂行時の大原則

コードベース・ドキュメントベースへの参照（何がどこにあるかの簡潔な説明）

情報収集に利用できるツールの列挙

よく繰り返す、ある程度定型的なフローはスキル化で対処。セルフレビュー、リファクタ、既存コンポーネント探し……

vector dbでドキュメントベースをindexしておいて、意味論的検索できるようにしておくのもたぶん効果があるが、これはメンテコストやコンテキスト管理手法によってはそこまで必要とはならない

ドキュメントベース自体がしっかり構造化されていればそれを辿るだけで良いが、ADRなどのような履歴積み上げ系ドキュメントに対する検索は、正直（シンプルな語句検索よりもワークする何らか、というレベル感で）できた方がいい

MSA（Micro Service Architecture）の設計概念などに登場するContractを意味しているのか

ProtoBufやOASなどでAPI表現が事前に共有されている程度（≒Schema駆動開発）を意味しているのか

で結構考え方変わってくると思う。前者のレベル間でやれるなら理想。後者はもはや常識なので、よほどの技術的都合がない限りは実現しよう。

陳腐化しやすいコメントを書かせない（人もCoding Agentも嘘コメントを信じて不幸になることがしばしばある）

派生として、「インデックスコメントを書きたくなる場合、命名がおかしい」という理解をしておく

反対に、仕様やその背景の説明はやや過剰な程度に書く

いかなる言語であっても宣言的に書ける場合は宣言的に書く方がよろしい、ということを徹底的に理解させる

実態と乖離していそうなコメントや命名があった際の判断を求めさせる

あとで書く