Claude Codeで良い結果を得る
(dzombak.com)- ここ数か月、さまざまな LLMプログラミングエージェント を試した結果、Claude Codeが最も満足度の高いツールだった
- Claude Codeのおかげで、短期間に約 12本のプログラムとプロジェクト を作成でき、普段なら時間の都合で着手しなかった作業にも取り組めるようになった
- 成功裏に活用するには、明確な仕様書の作成、プロジェクト構造・ビルド・lintの実行方法をまとめた文書の提供、AI自身へのコードレビュー依頼、そして個人用の グローバルエージェントガイド の運用が鍵となる
- AIが書いたコードはしばしば 不正確または非効率 になりうるため、すべてのコードとテストケースを必ず自分で確認し、不足しているテストは自分で追加するか、AIに作成させたうえで再レビューする
- 付録として公開されたグローバルエージェントガイドには、段階的な実装計画、テスト駆動開発、シンプルさ・明確さ・実用性を重視する哲学、品質基準、問題解決プロセスなどの 詳細な開発指針 が含まれている
Claude Code活用の経験と効果
- ここ数か月、さまざまな LLMプログラミングエージェント を試し、とくにClaude Codeの使用体験が最も優れていた
- まったく問題がないわけではないが、短期間で12本以上のプログラムやプロジェクトを完成させることができた
- Claude Codeなしで、同じ期間内にこれらすべての作業をこなすのはほぼ不可能だっただろう
- 多くは、時間がかかるという理由で、そもそも試すことさえしなかったはずのプロジェクトだった
Claude Code活用戦略
- 明確な仕様書を作成する
- プロジェクト開始前に、要件と文脈を明確に文書化してエージェントに渡す
- これにより、コード作成の方向性と範囲を明確にする
- プロジェクト構造を文書化する
- ビルド、lint、テストの実行方法を含む文書を用意する
- エージェントがコードベースをより効果的に探索し、作業できるようになる
- エージェントにコードレビューを依頼する
- Claude Codeに自分が生成したコードを直接レビューさせ、想定外の改善点やバグを見つける
- 個人用グローバルガイドを活用する
- 問題解決のアプローチ、TDDの適用、シンプルさ・明確さの維持、試行回数の制限（3回）など、個人ルールを記した
~/.claude/CLAUDE.mdにより、一貫した開発プロセスを維持する
- 問題解決のアプローチ、TDDの適用、シンプルさ・明確さの維持、試行回数の制限（3回）など、個人ルールを記した
LLMが書いたコードの検証
- AI生成コードにはしばしば 論理エラー、性能低下、不完全なテスト などの問題がある
- 著者はすべてのコードを 手動でレビュー し、動作を確認する
- 欠けているテストケースは自分で追加する
- あるいはAIに作成を依頼し、その後コードとテストを再確認する
- プロフェッショナルな環境では、PRに自分の名前が入る以上、最終的な品質責任は自分にある と強調している
個人用「グローバル」エージェントガイドの主な内容
このガイドは ~/.claude/CLAUDE.md ファイルで管理している
-
哲学と中核原則
- 段階的に進める: 小さな単位で変更し、常にコンパイルとテストを通す
- 既存コードを学ぶ: 実装前にコードのパターンを分析し、計画を立てる
- 実用性優先: プロジェクトの状況に応じた柔軟なアプローチ
- 明確さ優先: 読みやすく意図が明白なコードを重視し、不要なトリックを避ける
-
シンプルさの定義
- 関数・クラスは単一責任
- 早すぎる抽象化は避ける
- 複雑さを減らし、説明を必要としないコードを目指す
-
作業プロセス
- 1. 企画と段階設定:
- 複雑な作業は3〜5段階に分けて
IMPLEMENTATION_PLAN.mdに記録する - 各段階の目標、成功基準、テストケース、進捗状況を明記する
- 複雑な作業は3〜5段階に分けて
- 2. 実装フロー:
- 理解 → テスト作成（赤） → 最小実装（緑） → リファクタリング → コミット
- 3. 3回試してだめなら再評価:
- 失敗時は試行内容とエラー、原因を記録する
- 代替案を探る（2〜3通りのアプローチ）
- 根本的な設計や問題分解を見直す
- 別のパターンや機能を試す
- 1. 企画と段階設定:
-
技術標準
- コンポジション優先、依存性注入を活用する
- インターフェースを使う、テストしやすさを確保する
- 明示的なデータフロー
- TDDを推奨し、テストの無効化は禁止
-
コード品質ルール
- すべてのコミットでコンパイル成功、テスト通過、新機能のテスト追加、コードスタイル遵守を満たす
- コミット前にフォーマッタ・リンターを実行し、変更点をセルフレビューし、「なぜ」を説明するコミットメッセージを書く
-
エラー処理
- 早期失敗と具体的なメッセージ
- デバッグに必要なコンテキストを提供
- 適切なレベルで例外処理し、例外の隠蔽は禁止
-
意思決定基準
- 1. テストしやすさ
- 2. 6か月後でも理解できる可読性
- 3. プロジェクトのパターンとの一貫性
- 4. シンプルさ
- 5. 変更しやすさ
-
プロジェクト統合
- 類似機能を3つ以上分析する
- 既存のパターン・ライブラリを再利用する
- 同じテストユーティリティを使う
- 新しいツールの導入には強い理由が必要
-
品質ゲート
- すべてのテストに合格
- プロジェクトのルールを順守
- リンター警告なし
- コミットメッセージが明確
- 実装が計画と一致している
- TODOにはissue番号を含める
-
テスト指針
- 実装ではなく 振る舞い 中心のテスト
- 可能ならテストごとにアサーションは1つ
- シナリオを説明する明確な名前
- 既存のテストユーティリティを再利用する
- テストは決定論的であるべき
-
絶対禁止
--no-verifyでフックを回避する- テストを無効化する
- コンパイルできないコードをコミットする
- 検証のない推測
-
必ず実施すること
- 段階的なコミット
- 文書を継続的に更新する
- 既存実装から学ぶ
- 3回失敗したらアプローチを再評価する
Claude Codeで制作したオープンソースプロジェクト
- HTML/XML認識リバースプロキシ (cdzombak/xrp)
- VS Code Solarizedテーマ（ライト/ダーク） (cdzombak/dzsolarized-vscode)
- FlickrフォトストリームRSSジェネレーター (cdzombak/flickr-rss)
- Lychee写真ライブラリ用メタデータツール (cdzombak/lychee-meta-tool)
- macOSスクリーンロック状態のMQTTレポート (cdzombak/macos-screenlock-mqtt)
- Lychee Bird Buddy写真タイトル自動設定 (cdzombak/lychee-birb-title)
- ローカルLLMベースの写真自動分類 (cdzombak/lychee-ai-organizer)
- macOS向けソフトウェア一括インストール自動化 (cdzombak/mac-install)
- RSSサービスプロジェクト (cdzombak/rss.church)
- Flickr写真の全件/選択的エクスポートとメタデータ保持 (cdzombak/flickr-exporter)
- 静的HTMLギャラリージェネレーター (cdzombak/gallerygen)
5件のコメント
良い結果が出たというのは、誰かがすでに作ったコードをうまく参照したという意味でしょうか。
筆者がやっていることなんて、みんなとっくの昔にやっているのだから、どうでもいい自慢はやめて、
LLM同士で比較したときに、なぜClaudeが一番良かったと考えたのか、その根拠を書くほうがずっと意味のある文章になると思う。
実際に生成されたコードの比較、コンパイルエラーの頻度、文脈把握の安定性など。
実際のところ、文脈把握能力が最も優れているのはGeminiだ（100万トークン）。
役に立たないものばかり作って、文章だけやたらと長々と書いているね。
誰かにとっては役に立つかもしれませんね（笑）
Hacker News の意見
今日、Claude とコーディングエージェントで初めて本格的な成功体験を得た。以前は Cursor を使っていたが、今は Claude と他のものも試している。記事で言及されていたように、明確な仕様を書くことが鍵だった。2時間かけて12段階の文書を自分で書き、実装方法を整理し、背景情報も含めた。Claude はその手順に従って順番にコードを生成した。感覚的にはたぶん 6〜10 時間は節約できた。これから自分でレビューし、テストして、段階的に調整しながら機能を追加していくつもりだ。この成功の土台は、Claude がやるべきすべての手順を自分が明確に書いたことにある。つまり、全体の流れは自分が設計し、Claude は指示に従うだけという構図だ。この過程を通じて、中級以上の開発者は当面 AI に置き換えられないという確信が強まった。ただ、Claude が仕様を通して読み、整理された文書化済みのコードを吐き出す様子を見るのは本当に不思議な体験だった。自分で直接コーディングしなくていい点はすごい
自分はここまで準備しなくても Claude で良い結果を得ている。ほぼ自分でコードを書くときと同じように、一度に一段階ずつ Claude に依頼している。毎回、変更部分をすぐ適用してコミットし、その後 diff を確認する。もし Claude が変な結果を出したらすぐ修正を依頼する。そして、適用してほしい既存コードや関数リファレンスを自分で直接示す。このやり方なら、はるかに少ないタイピングと時間で素晴らしい結果を得られる
Naur の “Programming as Theory Building” を読んでみることを勧める。問題をどう理論的に理解し、自分でモデル化すべきかを学べる。そうしないと、LLM が独自の（しかも誤った）理論を作ってしまうことがある
“Programming as Theory Building” - Naur を読む
記事にあったように、明確な仕様は本当に重要だ。自分は Claude でプログラミング言語を作っているが、この点を身をもって感じている。プログラミングには本当に些細な選択の連続がある。明確にガイドしなければ、LLM は大半を推測で処理し、しばしば間違った選択をする。こうした小さなミスが複合的に積み重なって、誤った結果につながることがある
もしこういう仕様書の例を実際に共有してもらえるなら本当にありがたい。独学で開発しながら Claude Code を試している立場として、実際にどんな情報や深さが役に立つのかを把握するのに大いに助かりそうだ
実際には、中堅やシニアの開発者でも、きちんとした仕様書を書けない人はかなり多い。言いたいことの意図には共感する
~/.claude/CLAUDE.md を作ってルールを書くのは、実際のところあまり効果がない気がする。Claude は人間ではなく、コードの各行ごとに慎重に推論しているわけではない。主観的で曖昧な指針を書いても、実際にコードを変えることにはつながらない。そして 'context rot' という問題もある
（context rot の説明: LLM が長い会話や作業の途中で文脈を失ったり歪めたりする現象。参考リンク: https://news.ycombinator.com/item?id=44564248）
現実的には、単一ファイルにあらゆるルールを詰め込んで AI が勝手に守ってくれると期待するのは不可能だ。そうするなら、各ルールごとに sub-agent を作り、AI ではなく通常のパイプラインとして分離する必要がある。しかし、そうするとコストは指数関数的に増えてしまう
コストの問題なら、ワークフローが安定した後は安価な LLM を活用できる（運用コストは高いが）。ファインチューニング、プロンプト最適化、特化型 distillation 手法などでコスト削減は可能だ。この分野ではすでに多くの研究が行われている
CLAUDE.md にはどんな内容を入れるとよいのか気になる
ページ下部にあるサンプルプロジェクトを見ると、ほとんどが単一の特定目的に最適化されたソフトウェアだ。今後はオープンソースプロジェクトも、こうした形で一人のニーズを満たす非常に特化した姿へ進化していく気がする。こうしたソフトウェア（ユーティリティ）は、LLM が一回で生成する使い捨てコードになっていくのではないかと思う
Claude Code に対する自分のアプローチはずっと変化している。会社の大規模な Web アプリに Claude Code で本当に意味のある機能をそのまま貢献することには、まだ成功していない。仕様はある程度役に立つが、結局は妙な方向に流れがそれたり、誤った選択を繰り返すループに陥ったりする。これは Claude の限界かもしれないし、自分の仕様書がまだ十分に正確でないからかもしれない。かなり実験してきたが、「難しいもの」や「ドメイン知識を強く要するもの」では失敗が多く、もうあまり試さなくなった。その代わり、友人の勧めで、精神的負担がほぼないバックログ作業に Claude を使い始めた。たとえば、あまり愛着のない Playwright テストを新しいワークスペースに作る仕事を Claude にやらせてみたが、これは非常にうまくいった。ユーザー体験を人に説明するように Claude に伝え、dev サーバーのパスを指定した。Playwright MCP を使って、どの feature をどう使うかを調べ、実行手順を文書化し、テストを書き、エラーをデバッグするよう指示した。さらに、プロジェクト内の UI コードを探って data-testid セレクタを追加する作業も含めた。全体のプロセスは master task.md にまとめ、feature ごとの個別 task markdown も作るよう指示した。このやり方は非常に効果的だった。特に、2人のブラウザーユーザーが直感的でない形で相互作用する複雑な feature にも使ったが、100% 正確ではないにせよ、複雑であるほど少し多めのコンテキスト補正とコード修正が必要になるだけで、全体としては何日もかかる面倒な作業を一気に片付けてくれた
CLAUDE.md はできるだけ 100 行未満のミニマルなファイルに保つのが一番良かった。
1か月以上、毎日 Claude Code と作業している。Cursor、Q なども使ったが、Claude Code のほうがずっと優れている。記事で触れられていたコツも、自分が気づいた点とかなり重なっている。
追加でいくつか思うことを挙げると:
Web コンソールで Claude とのアイデアセッションから始める。プロジェクトの目標を説明し、ドメインモデリングとマイルストーンを大枠で構想する。小規模プロジェクトなら数時間の往復で整理できる。ここで CLAUDE.md の最初のバージョンができる
実際のプロジェクトを始めるとき、Claude は自分のグローバルな CLAUDE.md とプロジェクトの CLAUDE.md の両方を読んでから始める。毎セッションそうしている
進行中も、Claude Code にプロジェクトの CLAUDE.md を継続的に更新させている。計画に沿って進捗を記録し、セッションの終わりにはプロジェクトの要約、動作の仕組み、コードのたどり方などを書き込ませる。いわば長期記憶の役割で、効果は高かった
どれだけガイドラインが良くても、Claude には先走ろうとする傾向がある。だから、自分が関与する作業では必ず小さなインクリメントで段階的に集中させる。単発やプロトタイプなら、好きなように一気に実装させる
プロジェクトレベルの CLAUDE.md は長くしすぎず簡潔に保ち、より詳細な内容は下位フォルダに移したほうがいい。最上位は一種の地図として使う。feature を一つ計画するたびに、Claude が適切なフォルダを見て必要なコンテキストを参照しながら段階的な実装計画を立てる。各段階の終わりごとに、Claude に新しいコンテキストで実装計画を更新させる。こうするとコンテキストが次の段階へ自然に引き継がれ、ウィンドウもリセットして新鮮な気持ちで次の段階に入れる
Claude Code で Factorio 系の ASCII ゲームを作っている。初期段階ではほとんど監視せずにコードを書かせ、主要機能（保存/読み込み、オプション、デバッグ、マップ生成、建設、ベルト、製作、QoL など）の大半を一気に実装した。だが、細部を直そうとすると、たとえば移動を変えたらベルトが壊れるといった具合に、他の部分が次々と壊れていった。そこで Playwright の自動化も追加させたが、テストの質は低く、sleep 呼び出しだらけだった。コードを詳しく見ると、React フロントエンドと useEffect を使う構造になっており、まともなゲームエンジンの構造ではなかった。hook のルールも十分に守れておらず、タイミングの理解も弱かった。そこで今回は tick ベースのゲームエンジンを導入して、最初から作り直し始め、コードレビューも追加した。進む速度は遅くなったが、はるかに堅牢に開発できている。良いデモが完成したら Show HN で公開するつもりだ
自分のように Claude の仕事用と個人用のサブスクを両方使っている人なら、"alias claude-personal="CLAUDE_CONFIG_DIR=~/.claude-personal claude"" みたいな形でアカウント切り替えを簡単にできる
複数の Claude アカウントを効率よく使う方法ブログ
みんな「事前に明確な仕様書を書いて context を与えるのが鍵だ」と言うが、自分の経験ではこれが常にうまくいくわけではない。実際に専門家と並んで Opus 4 & Sonnet 4 で CC セッションをやったことがあるが、相手は本当に明確な spec を用意していたのに、自分のやり方（思いついた機能ごとに、CLAUDE.md なしで、その都度それぞれの context を与えて頼む）より特に良い結果にはならなかった。仕様ベースの workflow は重要なことを忘れ続けたり、コンテキスト文書にないことを勝手に作り出したり（禁止されていることさえ）、一方で自分は、たとえば「invoice 用の CRUD ページを追加して、まずはコードベースの分析から始めて」といった即時の指示のほうがうまくいった。これはあくまで自分の経験談にすぎないが、実際に Claude で 100 件を超えるプロジェクトを進めてきた結果、Claude の暴走を防ぐための別フック以外に、特定のやり方がより優れているとは確信できない。多くの人が「仕様ベースのほうがいい」と言っていても、実際に見せてもらうと、むしろ明らかに間違っている部分を直すことに過剰な時間を費やしていることが多かった。しかも、CLAUDE.md に「こういうことは絶対にするな」と書いてあっても、結局それをやってしまう傾向があった