ハクソク

世界を動かす技術を、日本語で。

「Claude Code」を活用して良い結果を得る

290日前原文(dzombak.com)

概要

  • Claude Code を活用した LLMプログラミングエージェント の実践的な利用体験
  • 効率的な開発手法 や プロジェクト管理ガイド の共有
  • AIコードの検証 と 品質担保 の重要性の強調
  • 個人用グローバルガイドライン による開発標準化
  • Claude Code で作成した 主なプロジェクト一覧 の紹介

Claude Codeを活用したLLMプログラミングの実践

  • Claude Code を使うことで、短期間で 12件以上のプログラムやプロジェクト を開発
  • 従来なら手間がかかりすぎて着手しなかった アイデアも、Claude Codeのおかげで実現
  • 専門家でなくとも、事前学習や全てのドキュメント読破は不要で、 すぐに成果を得られる 利便性
  • 明確な仕様書 を先に用意し、エージェントに 十分な文脈 を与えることが成功の鍵
  • プロジェクト構造やビルド・リンター実行方法 をまとめたドキュメントも有効

Claude Code活用のポイント

  • エージェント自身にコードレビュー を依頼することで、多くの改善点発見
  • 個人用グローバルガイド（~/.claude/CLAUDE.md） を用いて、エージェントの行動基準やTDD等のベストプラクティスを明文化
  • AI生成コードの検証 は必須であり、 最終的な責任は自分自身 にあるという意識
  • 全てのAI生成コード・テストケースを手動でレビュー し、不足分は追加で作成・検証

個人用グローバルエージェントガイドの要点

  • インクリメンタルな進歩重視、大規模変更より小さな積み重ね
  • 既存コードから学び、計画を立てて実装 する姿勢
  • プロジェクト現実に即した柔軟な対応、原理主義より実利優先
  • 意図が明確なコード を重視、複雑なテクニックの回避
  • 単一責任原則、早すぎる抽象化の回避、説明が必要な複雑さの排除

プロセス・技術基準

  • 作業分割・段階的実装 ："IMPLEMENTATION_PLAN.md"で3～5段階に分割し進捗管理
  • テスト駆動開発（TDD） を基本とし、最小限の実装→リファクタ→コミットの流れ
  • 3回失敗したら立ち止まる ルール、失敗内容の記録・代替案の調査・根本的な見直し
  • アーキテクチャ原則 ：合成重視・依存性注入・明示的なデータフロー・テスト容易性重視
  • コード品質基準 ：全コミットでコンパイル・テスト合格・新機能にはテスト必須・フォーマッタ/リンター遵守
  • エラーハンドリング ：即時失敗・詳細なエラー情報・適切な階層で処理・例外の黙殺禁止
  • 意思決定基準 ：テスト容易性・可読性・一貫性・単純さ・可逆性の順

プロジェクト統合・品質ゲート

  • 既存コードベースの学習 ：類似機能の調査・パターン把握・既存ユーティリティ活用
  • ツール類は既存プロジェクト設定準拠、新規導入は慎重に判断
  • 定義されたDone条件 ：テスト合格・コード規約遵守・警告ゼロ・計画通りの実装・TODO管理
  • テスト指針 ：振る舞い重視・1テスト1アサーション・明確なテスト名・既存ユーティリティ活用・決定論的テスト

重要な注意事項

  • 絶対にしてはいけないこと ：--no-verifyでフック回避、テスト無効化、未コンパイルコードのコミット、未検証の思い込み
  • 必ず守ること ：動作するコードのインクリメンタルコミット、計画ドキュメントの逐次更新、既存実装からの学習、3回失敗後の再考

Claude Codeで作成した主なプロジェクト一覧

  • xrp ：HTML/XML対応リバースプロキシ
  • dzsolarized-vscode ：VS Code用Solarizedカラーテーマ（ライト/ダーク両対応）
  • flickr-rss ：FlickrフォトストリームやFriends & Familyフィード用RSS生成ツール
  • lychee-meta-tool ：Lycheeフォトライブラリ内の無題写真の検索・編集ツール
  • macos-screenlock-mqtt ：macOSの画面ロック状態をMQTTブローカーへ報告
  • lychee-birb-title ：LycheeフォトライブラリのBird Buddy写真タイトル設定ツール
  • lychee-ai-organizer ：ローカルLLMを活用したLychee写真整理ツール
  • mac-install ：macOS用の冪等なソフトウェア一括インストーラ
  • rss.church ：RSSの価値を訴えるプロジェクト
  • flickr-exporter ：Flickr写真・メタデータの一括エクスポートツール
  • gallerygen ：画像ディレクトリツリーから静的HTMLギャラリー生成ツール

Claude CodeとLLMエージェントの活用により、 開発効率の飛躍的向上 と 品質担保のための仕組み化 が実現可能。 個人ガイドライン の整備と 徹底した検証プロセス が、AI支援開発の成功の鍵。

Hackerたちの意見

今日は、Claudeを使って初めて本格的な成功を収めたばかりなんだ（エージェント全般についてもね）。以前はCursorを使ってたけど、今はClaudeや他のエージェントを試してる。記事にも書いてあったけど、重要なのは明確な仕様書を持つことだね。私の場合、2時間かけて実装方法を12ステップにまとめたドキュメントを書いたんだ（背景情報も含めて）。Claudeはそのステップを一つずつ進んで、コードを書いてくれた。これで6〜10時間は節約できたと思う。今はレビュー中で、テストしたり調整したり、将来の機能を追加したりする予定。成功の理由は、必要なことをどうやってやるかを正確に把握していたからだね。全てのステップを書き出したら、Claudeがそれに従ってくれた。これで、中堅やシニアの開発者が必要だってことがはっきりしたよ。とはいえ、要件をクリアして、私が書かなくても整理されたドキュメント付きのモジュールを実装してくれるのを見るのは本当にすごかった。

└

正直、Claudeを完全に無視しても、自分のために良い仕様書を書くことは価値のある取り組みだよ。

└

次回はClaudeを使って仕様書を書いてみてね。

└

その仕様書の例を共有してもらえないかな？アマチュアプログラマーとしてCCを試しているから、役立つ情報の性質や深さを理解するのがすごく助かるんだ。

└

とはいえ、要件をクリアして、私が書かなくても整理されたドキュメント付きのモジュールを実装してくれるのを見るのは本当にすごかった。ちょっとしたサイドノートだけど、AIが生成したコードに対するAI生成のドキュメントって、どれくらい価値があるのかな。AIが既存のコードを再分析したり変更したりするたびに、コンテキストのサイズが増えるだけの負担になってる気がする。人間がコードのドキュメントを読むことなんてないし、AIにその内容を聞けばいいんだから。

└

カーソルを通して同じスペックを送れないの？何か見落としてるかな？

└

中堅や上級の開発者の多くは、スペックを書くのが苦手なんだよね。あなたの言ってることには賛成だよ。

└

最近、誰かが言ってたけど、ChatGPT Deep Researchの助けを借りて、すごく詳細な仕様書を書くようになったんだ。それをMarkdownドキュメントとしてエクスポートして、Cursorに渡すのがすごくうまくいった。あまり繰り返し考えすぎず、じっくり考えるための心のスペースができるから、最終的にはあまり成果を上げられずにぐるぐる回っている感じがなくなるんだよね。

└

昨日、私もプロジェクトでClaudeがコードを書くのを初めて良い経験をしたよ。初めてプランモードを使って、「もっと考えて」って促してみた。簡単な改善だったけど、決して trivial ではなかった。仕様書もそんなに詳細じゃなかったし、特定のクラスと変更すべき動作をいくつか挙げただけで、私が書くであろうコードを期待通りに書いてくれたし、私がやるよりも少し安全性のチェックが多かった。

└

私もそうやって使ってた。要件を全部まとめたドキュメントを作って、それをCCに渡したんだ。でもそれは最終的なドキュメントじゃなくて、CCが作ったコードを試した後に戻って修正する必要があった。

└

うん。「Programming as Theory Building」っていうNaurの本を読んでみて。問題の理論をちゃんと作る必要がある理由や、自分でモデル化する方法がわかるよ。そうしないと、LLMが（間違った）理論を作っちゃうからね。

エージェントに自分の作業のコードレビューをさせるのは、意外と効果的だよ。私はいつもその提案を使って、適用する前にレビューしてる。Claudeが自分の最後の出力をすぐに否定することが多くて、私たち二人とも納得する理由があるんだ。これを自動化できたらいいな。

└

しばらくの間、Claudeは自分の作品をレビューする時、ちょっとネガティブすぎるくらいだったんだよね。考えてみて初めて気づいたんだけど、コードレビューのスラッシュコマンドの言い回しが、レビューをネガティブにしてしまってたんだ。要するに、Claudeに自分の作品をけなすように促してたってこと。だから、そのプロンプトの言い回しには、ずっと気を使ってるんだ。

└

サブエージェントの良い使い方みたいだね。 https://docs.anthropic.com/en/docs/claude-code/sub-agents

Claude Codeを使って、ASCIIのFactorioみたいなものを作ってるよ。最初はあまりコードの監視をせずにコードを書かせたんだ。すぐに期待されるコア機能（セーブ/ロード、オプション、デバッグ、建設、マップ生成、ベルト、クラフト、スマートベルト配置、QoL）をほとんど追加してくれた。その後、ちょっとしたバグを修正し始めたら、毎回何かが壊れちゃって、例えば動きを調整したらベルトが壊れた。そこでPlaywrightの自動化を追加するように促したんだけど、質の良いテストを書けなくて、全部通らなかった。テストはスリープコールだらけだったりして…。だからコードをじっくり見たら、ReactのフロントエンドとuseEffectを使っていて、ちゃんとしたゲームエンジンを使ってなかった。フックのルールを守るのも苦手で、タイミングを理解するのも難しいみたい。だから今は、ちゃんとしたティックベースのゲームエンジンを使うように促して、ゲームを再構築してるところ。今は「遅く」なってるけど、ずっと良くなってきてるよ。良いデモができたらShow HNに投稿するのが目標。

└

そうそう、人間の貢献はすごく価値があるよ。特にAIが動き始める前の初期段階ではね。最初の大きなリファクタリングは、鷹のように見守らないといけない。そこを乗り越えたら、少しリラックスできるよ。

ここ1ヶ月ほど、毎日Claude Codeを使ってるけど、かなり優秀で、他のエージェント（CursorやQ）よりも良いよ。この文章には、私が学んできたことを反映した良いヒントがいくつかある。いくつかの追加の考えを挙げると： - Claudeとウェブコンソールでアイデア出しのセッションを始めるのが好き。プロジェクトの目標を説明して、高レベルのドメインモデリングを進めて、プロジェクトをマイルストーンに分けて、リリース可能な目標を設定する。小さなプロジェクトなら、これに数時間かかることもある。この結果が最初のCLAUDE.mdのバージョンになる。 - それからClaude Codeでプロジェクトを始めて、グローバルなCLAUDE.mdとプロジェクトのCLAUDE.mdを読ませて、進めていく。各セッションはこうやって始まる。 - Claude Codeに進行状況をプロジェクトのCLAUDE.mdに更新させる。進行状況をマークさせながら進める。通常、セッションの終わりには、プロジェクトの要約、動作方法、コードのナビゲート方法を含む特別なセクションを書き直させる。これをClaudeの長期記憶みたいに扱ってる。これがすごく役立つことが分かった。 - 良いガイドラインがあっても、Claudeは自分のペースを超えて進もうとする傾向があるみたい。私は、気に入っていることなら自分がやるように小さな増分を作るようにしてる。もし一回限りのものやプロトタイプなら、好きにさせて、うまくいくものを作らせるよ。

└

$20のサブスクリプションは、カーソルと同じくらいお得なのかな？ツールには興味があるけど、日常的に使うにはもっと投資が必要なのか気になる。

Claude Codeを定期的に使ってて、同僚にも紹介してるんだけど、ここでのコンセンサスは「最高のコーディングエージェント」ってことみたい。でも、私が使った唯一のコーディングエージェントだから、同僚が「CursorやCline、GitHub Copilot、Gemini CLIより何がいいの？」って聞いてきた時、理由をうまく説明できないことがあるんだ。Claude Codeのパワーユーザーたち、他のエージェントより優れてる理由は何だと思う？

└

これ、別のコメントでも言ったんだけど、私にとっての大きなプラスはモデルとは関係なく、UIの見せ方なんだ。最初はCursorみたいにIDEに座ってないのが嫌だったんだけど、Cursorを全然違う使い方してたことに気づいたんだ。小さなタスクで使うことが多くて、そこまで役立たない（リファクタリングや小さな関数追加、自動補完）感じだったから。Claudeを使う時は、立ち止まって考えて計画を立てる必要があるから、よりインパクトのある変更をもたらしてくれる。言い換えれば、私にもっと要求してくるから、より敬意を持って接するようになって、その分多くの成果を得られるんだ。

└

パワーユーザーではないけど、最近Geminiと比べてみたら、Claudeはコンパイルできてほぼ動くものを生成したんだ。細かい部分でちょっと調整が必要だったけど、次に聞いたことはほぼ完璧にこなしてくれた。一方、Geminiはコンパイル→失敗→修正しようとする→コンパイル→また失敗のループにはまっちゃって、最終的には「これを解決できない」って諦めちゃったみたい。こういうシナリオでは、自己評価に問題があるように見えるけど、Claudeは自信満々なんだよね（必ずしも良いことではないかもしれないけど）。Claudeは実際に動くものを作るのが一番得意な気がする。Geminiは価格の面でも厳しい競争相手になると思うけど、Googleはもうちょっと質の向上が必要だね。無料のAIエージェントは、何も解決できないなら価値がないから。

└

OpusとSonnetモデルは、コーディングやツールの使い方、長い文脈での問題解決において、根本的に優れているという結論に至るサインがたくさんあるよね。彼らのモデルのトレーニング方法には、何か特別な秘密があるみたい。ダリオはインタビューで、この強みが会社の厳重に守られた秘密の一つだって言ってたし。この能力を正確に測るための評価基準はまだあまり良くないと思う。SWE Benchはそこそこ良さそうだけど、ClaudeがGPT 5よりもコーディングが得意だっていう体験談が結構出てきてるよね、SWE Benchのスコアは似たようなもんだけど。

プロジェクトレベルのCLAUDE.mdファイルを簡潔にまとめることを強くお勧めするよ。もっと細かいことはサブフォルダに振り分けて。トップレベルを地図として使うんだ。機能の計画を立てる時には、各フォルダに必要なコンテキストを見つけに行くようにしてる。思考モードを使って、正しいコンテキストを見つけるようにしてるよ。各フェーズの終わりには、Claudeに新しいインスタンスのために新しいコンテキストで実装計画を更新するように頼んでる。この方法でコンテキストを前に進めて、次のフェーズに向けて新たにスタートできるようにしてるんだ。

私みたいに仕事と個人のClaudeサブスクリプションを管理するのに苦労している人には、こんなエイリアスを使うといいよ：alias claude-personal="CLAUDE_CONFIG_DIR=~/.claude-personal claude" https://julesrosser.com/blog/Multiple-Claude-accounts.html

私は構造化された仕様書は書かないけど、それでもたくさんの価値を得てるよ。基本的には、もっと低いレベルで何をしたいかを伝えながら、段階的に使ってる。何をしているか常に見ていて、行動を修正するために止めたりもする。少なくとも私には、このアプローチの方が大きなことを頼むよりもずっと効果的だった。

誰か、実際には時間をかける価値がないプロジェクトを始めちゃって、優先度が高いタスクに対してはClaude Codeを避けてるって感じる人いる？古い大きなゴチャゴチャしたプロジェクトの機能にClaude Codeを使って成功した人いる？

これらのエージェントの魔法は、彼らが以前に見た仕事をどれだけ早く、柔軟に盗用できるかってことだよね。