ハクソク

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

複雑なコードベースでAIを活用する

244日前原文(github.com)

概要

humanlayer による advanced-context-engineering-for-coding-agents は、コーディングエージェントの高度なコンテキスト設計手法を解説。 GitHub上で スター161件、 フォーク12件 の人気リポジトリ。 通知設定には サインイン が必要。 主な内容は コーディングエージェント の文脈理解向上技術。 エージェント設計やAI開発者に有用な情報を提供。

advanced-context-engineering-for-coding-agents リポジトリ概要

  • humanlayer が公開する GitHubリポジトリ
  • コーディングエージェント向けの 高度なコンテキストエンジニアリング 手法
  • AIエージェント の文脈理解やタスク遂行能力の向上を目的
  • README やドキュメントで設計思想や活用事例を詳述
  • スター161件、 フォーク12件 のコミュニティ人気
  • 通知設定 はGitHubアカウントで サインイン 後に変更可能
  • 開発者や研究者向けの 参考実装 やベストプラクティス

主な特徴と内容

  • コーディングエージェント の文脈理解を強化する設計指針
  • プロンプト設計 や 情報抽出 の具体例
  • タスク分解や指示生成の アルゴリズム
  • AIエージェント のパフォーマンス向上を目指す技術
  • 実装例 や 活用事例 の紹介

利用方法・コミュニティ

  • GitHub 上での公開、誰でも閲覧・利用可能
  • スター や フォーク でコミュニティ貢献
  • Issue や Pull Request での議論・改善提案
  • 通知設定は サインイン 後に変更可能
  • AI開発者 や 研究者 の情報交換の場

Hackerたちの意見

まだ「委任」と「抽象化」の境界をみんなで模索してる感じだね。個人的には、これらは同じじゃないと思うけど、確かに関係はあるし、ちょっと目を細めれば、いろんな状況でどちらかを主張できるよね。

「私たちは、300k LOCのRustコードベースを扱うためにClaude Codeを使い、1日で1週間分の作業を終わらせ、専門家のレビューを通過するコード品質を維持しています。」 これって、他のエンジニアにコーディングタスクを委任してレビューするのと似てる気がする。 「2年後には、今のようにアセンブリを読むためにhexエディタを開く頻度で、IDEでPythonファイルを開くことになるでしょう（ほとんどの人にとっては、そんなことはないけど）。」 これは、PythonをCの上にある高レベルのレイヤー、Cをアセンブリの上にある高レベルのレイヤーと考えると、抽象化に近い気がする。ただ、今の言語は英語になってるけど。両方であることって本当に可能なのかな？

└

もっと抽象化と、その抽象化がもたらすレバレッジについてのことだと思う。私が「仕様駆動開発」について話すとき、実際に証明した戦術的なことのほとんどは、良い仕様があってこそ成り立つことに気づくはず。でも結局、良い仕様が「正しい抽象化」だと思うし、これらのテクニックのほとんどは実装の詳細として落ち着く。サンディ・メッツの言葉を借りると、間違った抽象化に対して構築するより、詳細に留まる方がいいよね（https://sandimetz.com/blog/2016/1/20/the-wrong-abstraction）。委任は正しくないと思う。私とヴァイバフが1日で1週間分の作業を終えたとき、私たちはその作業に深く関与していて、デスクから離れず、常に再調整していて、その日は50件以上のユーザーメッセージを送ったし、マークダウンファイルのポイント編集もしてた。

もし「研究 -> 計画 -> 実装」のアプローチを試してないなら、LLMの良さを見逃してるよ。これで私の視点が完全に変わった。重要なのは、異なるレベルの抽象化を意識的に考えることだった。以前はやってたけど、明確なステップでやってなかったから、混乱してたんだよね。前のアプローチだとチェックポイントやリバートがすごく難しかった。すべてをフェーズで考えると、gitのコミットも「フェーズ」レベルで似たようなことをやって、デザインの決定がしやすくなる。最後にすべてが動いたら、4〜5時間かけてコードをきれいにするけど、それでも自分でハードな機能を書くよりはずっと早いよ。

└

正直言って、この新しいアプローチを多くの人が受け入れにくくしているのは「vibecoding」って言葉だと思う。確かに、「XYZをするアプリをくれ」みたいな愛らしい感じのvibecodingは明らかに馬鹿げてるし、雑な結果になるよね。真剣なアプリを「バイブス」で作るのは愚かだ。でも、もしこれを正しくやっているなら、伝統的な意味で「コーディング」しているわけじゃないし、絶対にバイブスに頼っているわけでもない。新しい言葉が必要かもね。

└

でも明確なステップでやってなかったから、混乱してたんだよね。これを何度も言ってるけど、私は主にボイラープレートコードに使ってるし、頭が働かないときに使うことが多い。自分で解決するのは好きだけど、AIは「x, y, zが欲しい」と思ってるところから「お、30分以内にx, y, zに到達した！」って感じにしてくれる。これはサイドプロジェクトにはいいと思う。少しずつやるなら、ほとんどいつでも大丈夫だと思う。あまりにも多くを頼もうとすると、あなたもモデルもエッジケースを考慮しなくなって、最終的には厳しい現実に直面することになるかも。

大規模なコードベース作業用に作ったパッケージがあるんだ[0]。/featureから始まって、説明を受け取る。そしたらコードベースを分析して質問をしてくる。質問に答えると、マークダウンで計画を書いてくれる。やりたいことの説明とフルコードサンプルが入った8〜10個のマークダウンファイルができる。次に「コード批評」のステップがあって、エラーを探すんだけど、重要なのは、このコード批評が60%の確率で間違ってるってこと。批評を見直して、彼が作り出したいくつかのバカな問題を消す。そうすると、変更内容の簡潔なフォルダと元の説明が揃って、チェックも終わってる。あとは「行け！」ってClaude Codeに言うだけで、特定のタスクを進めてくれる。これで脱線を防げるし、彼が行った変更が自分の望んでいたものだって自信が持てる。これを1日に何回か大きなタスクに使って、具体的なことを頼むときは普通のClaude Codeを使ってる。かなり効率的なワークフローだよ。[0] GitHub.com/iambateman/speedrun

作者がこの35K LOCを7時間で研究して実装したって自慢してるのは変だよね。でも、7日間で40のコミットがある。1日1時間だったの？それに、最近のコミットの一つが「いくつかのテストを無視」ってのも面白いね :D

└

もしさらに読み進めると、私はこれを認めてるよ。

「キャンセルPRは、ラインを越えるためにもう少し手を加える必要がありましたが、私たちはたった1日で素晴らしい進展を得ました。」

この記事は、私が正確に諦めた（7月に）時点のブックマークみたいなものだね。コードの各部分について、別のフォルダーに仕様書を作って、そこで作業した機能のログを管理してた。Pythonで作ったAPIサーバーで、アカウント、通知、サブスクリプションなどの多くのサービスがあったんだ。管理がすごく難しくなってきて、Claudeはビジネスロジックを正しく判断できなくなってしまった。例えば、アカウントとプロファイルを結ぶ役割の結合テーブルを使ったシンプルなRBACシステムを作りたいときとかね。結局、うまくいったのは、関係性を示すUML図を例付きで渡して、理解させて行動を改善させる必要があったってこと。

└

これが、最初にresearch_codebase.mdを作った大きな理由の一つだと思う。最も重要な懸念は「このコードベースを所有することになったけど、どう動いているか分からない/進め方が分からない場合、どうなるのか」ってこと。主にAIが書いたコードには2つの共通の問題がある。1つ目は、慣れないコードベース -> リサーチをすれば、フローや機能についてすぐに理解できる。2つ目は、大きなPRレビューが面倒 -> 計画を立てることで、何が変わっているのか、なぜ変わっているのかの整理されたコンテキストが得られる。Mitchellはスレッド共有のためにampcodeを称賛していて、これは#2の良い解決策だね。

数週間後、@hellovaiと一緒に35,000行のコードをBAMLに出荷して、キャンセルサポートとWASMコンパイルを追加したんだ。チームはそれぞれの機能に、シニアエンジニアが3〜5日かかると見積もってた。ごめん、彼らは実際にエンジニアが1日に4,000〜6,000行のコードを作るべきだと見積もってたの？

└

ここで欠けている詳細は、シニアエンジニアならおそらく2,000行のコードで出荷していたってことだね。

このパターンは、2つの異なるコードベースで使ったことがある。一つは約50万行のApache Airflowのモノリスリポジトリ（私はデータエンジニア）。もう一つはグリーンフィールドのFlutterサイドプロジェクト（DartやFlutter、モバイル開発についてはあまり知らない）。ただ、これがうまくいくことは分かってる。グリーンフィールドプロジェクトでは、コードがシンプルすぎてほとんど/create_planを実行するだけでリサーチをスキップできる。エージェントの利点も得られるしね。重要なのは、AIが出力するドキュメントを本当にレビューすること。心配しているエッジケースがカバーされているか、適切な技術が選ばれているかを自問自答してみて。例えば、SQLiteパターンから抜け出してPostgresを使うことを提案したかどうか。こういうのは一瞬で確認できるとてもシンプルなチェックだよ。プランが作成された後にエージェントとチャットするだけで、Claudeコードを使ってそのままプランを直接編集できる。私の仕事ではGitHub Copilotを使っているから、プロンプトを少し調整する必要があったけど、ステップ間の意図的な圧縮はまだ起こる。効率は少し落ちるけど、CopilotはClaudeコードのようにサブエージェントをサポートしていないからね。それでも、生産性は維持できてる。------- 個人的な話だけど、AI支援のコーディングが本格化する前に、仕事がすごく退屈になってきて、すごく落ち込んでた。全てがただの面倒に感じてた。大規模なコードベースでは、複数のリポジトリ、チーム、個性などの相互作用や特異性によって、まさに「千の紙切れによる死」が現実になる。私にとって、AI支援のコーディングの主な利点は、その紙切れを和らげることのようだ。うまく機能するものを作ることに喜びを感じてる。最終的な目標を妨げる小さなことが、私が一日中やろうとしていた活動から楽しみを奪っていた。今は、続ければ自分が作れるものに感動して、ずっと幸せだよ。

こんなに詳細な記事を書いてくれてありがとう…たくさんのよくサポートされた情報がある。私は「Micromanaged Driven Development」って呼んでいるものに取り組んでいて、https://mmdd.dev でそれについて書いたんだ。私は似たような探求をしていて、AIと共にコーディングする多くの人々がこの方向に進んでいるのを見てワクワクしてる。まだまだ学ぶことがたくさんあるね。

私はGPT Proと、複数のファイルから一度にコードをコピーするのが簡単になるVS拡張機能を使ってる。新しいSaaSのバージョンを設計していて、バックエンドのすべてを生成してもらってる。モデリングやコーディングに大きな助けになってるけど、かなりの調整と修正が必要だね。一人でやるよりも良い結果が得られると思う。なぜなら、私が知らない多くのパターンや詳細（RRULEのようなシンプルなことまで）を知っているから。初期の構造が整ってきちんと文書化されれば、Codexが新しいテーブルやサービスを簡単に作成できるように、よりシンプルで縦のアーキテクチャでこの新しいプロジェクトを設計してる。編集: タイポ。

└

そうだね、フラットでシンプルなコードはスタートにはいいけど、「いつ重複コードが広がるのを許すか」と「いつDRYポリスになるべきか」のバランスをまだ掴んでいるところだよ。

これを言うためにアカウント作ったんだけど、RepoPromptの「コンテキストビルダー」機能が、コードに手をつける前にコンテキストを把握するのにめっちゃ役立つんだよね。まるでRepomixやGitingestとチャットして、プランニング用にコードベースの中から一番関連性の高い部分だけを引っ張ってきてもらうみたいな感じ。俺はRepoPromptの有料ユーザーだけど、他には何も関係ないよ。CodexやClaude Code、今まで試した他のコード生成ツールと一緒に使ってるけど、トークンや時間（それに頭痛も）をかなり節約できるよ。