はじめに
学生チーム所属の井田です。
私たちのチームでは、毎週の読書会で『実践Claude Code入門―現場で活用するためのAIコーディングの思考法』を題材に輪読を行いました。
Claude Codeの登場によって開発体験は大きく変わりつつありますが、同時に現場で使ってみると見えてくる課題や、うまくいかない場面も多くあります。
本を使って体系的に学び、個人やチームでの開発にどう落とし込んでいくかをつかむ目的で、本書を選定しました。
本記事では、本から得た学び、それを実際の開発で取り組んでみた効果と課題、そして参加メンバーの感想を紹介します。
読書会を振り返って
以前『SQLアンチパターン 第2版』を題材にした読書会では、議論が盛り上がった一方で、読み終えるまでに半年ほどかかりました。 （その時の様子は以下の記事まとめてあります）
今回は、短期間で開発にすぐ活かせるテーマとして『実践Claude Code入門』を選びました。
部内では、大きな開発プロジェクトの真っ最中ということもあり、進めていくうちに参加メンバーも開発タスクに追われ、人数が限られる回や開催を見送る回も出てきました。
タスクに追われると、どうしても勉強会の開催ハードルは上がってしまいます。
それでも、学びをすぐに実践へ移しながら議論でき、結果として密度の濃い時間になったと感じています。
本での学び
AIエージェントが直面する「3つの壁」
Claude Codeを使っていると、AIエージェントの仕組み上、避けて通れないつまずきにぶつかります。本書で挙げられている主な課題は以下の3点です。
① 記憶の消失（トークン圧迫）
Claude Codeとのやり取りが長くなったり、AIが何度もコンパイルやテストを繰り返して大量のログが出力されたりすると、それ自体がトークンを大きく消費します。会話が長くなるとコンテキストウィンドウが自動圧縮され、最初に伝えたはずの「重要なルール」や「実装の前提条件」をAIが忘れてしまうことがあります。
② 指示の不一致（暗黙の了解の欠如）
人間側の「言わなくても分かるだろう」という暗黙の了解が言語化されていないと、指示書と既存のコードガイドラインの間で矛盾が起き、AIが意図しない方向に迷走し始めます。
③ 連携の壁（外部コンテキストの不足）
AIがローカルのファイルしか見えていない場合、最新の公式ドキュメントや外部APIの仕様、あるいはブラウザ上での実際の挙動と適切に連携できず、古い知識に基づいたコードを生成してしまうことがあります。
課題に対する解決策：「スペック駆動開発」
思いつきで指示を投げ続ける開発は、手戻りを増やし、技術的負債を積み上げる原因になります。これらを防ぐための本書の中心的な学びが、実際にコードを書かせる前に「AIと仕様（スペック）を合意する」というアプローチです。
ドキュメントの二層構造によるコンテキスト管理
プロジェクトのドキュメントを以下のように明確に切り分け、AIが読み込むべきコンテキストを制御します。
- 永続ドキュメント（
docs/）：プロジェクトの軸となる不変のドキュメント（PRD、全体のアーキテクチャ設計、コーディング規約など）。 - 作業ドキュメント（
.steering/）：今回の作業（タスク）単位で使い捨てるドキュメント（要件定義、タスクリスト、一時的な設計書）。
実装前にAIと一緒に .steering/ のタスクリストを整理する。この「ステアリング（舵取り）」を挟むことで、AIの迷走を大きく減らせます。
Claude Codeの機能を活用する
コンテキストを汚さないために、以下の工夫も紹介されています。
/clearの適切な実行：トークン増大による性能低下を防ぐため、1つのタスクが終わったらチャット履歴をクリアする。- スキルの整理：特有の知見や手順を「スキル」としてClaude Codeに学習させ、テキストによるコンテキスト圧迫を防ぐ。
- サブエージェントの活用：実装コードのレビューや仕様ドキュメントの検証、テストやログチェックといった作業を、別プロセス（サブエージェント）に切り出して任せる。
本書が発売されたのは2025年12月ですが、今となってはこうした「スキル」や「サブエージェント」の活用も、現場では一般的なものになってきたと感じています。
実践：スペック駆動開発を試してみて
本書の学びは読んで終わりにせず、実際の新規事業の開発に取り入れてみました。本で紹介されている steering スキルを参考に、.steering/ を使って以下の流れで進めるようにしました。
- 機能仕様の調査：実装に入る前に、関連する既存仕様やコードをAIに調査させる
- 要件と設計の整理：今回実装する要件と設計方針をドキュメントにまとめる
- タスクリスト化：要件・設計をもとにタスクを分解し、上から順に実装させる
作業ごとに .steering/[日付]-[機能名]/ ディレクトリを切り、3つのドキュメントに分けて管理しました。
.steering/[日付]-[機能名]/ ├── requirements.md # 要件 ├── design.md # 設計方針 └── tasklist.md # 実装タスク（フェーズ・サブタスク・順序まで具体化）
requirements.md と design.md で「何を・どう作るか」を固めてから、tasklist.md に実装手順まで落とし込むのがポイントです。
やってみて感じた効果
まず、何を作るかを仕様として明文化し、タスクに分解してから実装に入ることで、実装後の手戻りが大きく減りました。一つひとつの作業の見通しが立つため、スムーズに進められるようになったのが一番の効果です。
また、判断の根拠が .steering/ のドキュメントに残るため、AIと長いやり取りを重ねなくても進められ、コンテキストが汚れにくくなったのも実感しています。
一方で見えてきた課題
実際に試してみて見える課題もありました。
- 既存コードに引っ張られる：調査フェーズで既存コードを読み込ませると、「本来あるべき設計」よりも「既存実装に寄せた設計」が出てきやすい。気をつけないと、設計が既存コードベースに引っ張られてしまいます。
- 生成物を鵜呑みにしがち：出てきた設計やタスクリストは一見もっともらしく、批判的に検証しないまま進めてしまう場面がありました。タスクに追われているときほど抜け漏れが起きやすく、かえって負債が溜まりかねません。
- レビューがボトルネックになる：実装スピードが上がった分、生成物のチェックがそのまま人間側の負担となり、レビューが追いつかなくなりやすい。
- ドキュメントの運用：スキルやコマンド、仕様駆動のドキュメントは個人に依存しやすく、チームとして運用するにはまだ課題が残ります。まずは属人的なノウハウに頼るより、規約のような形でチームの土台を揃えるほうが、結果的に運用しやすいのではないかと考えています。
本書でメインだったゼロイチ開発とは異なり、大規模で複雑な既存プロダクトでは、AIに全自動で丸投げするのはまだ怖さがあります。
それでも、ドキュメントを整える過程で「人間にとっても見通しの良い、負債の少ない設計」が自然とできあがっていくことも感じます。こうした積み重ねが、結果的にプロダクトの保守性を高める力になると感じています。
感想：参加メンバーが感じたこと
エンジニアの仕事は「意思決定」へ 古堅
Claude Codeに感じた「焦り」
Claude Codeを使い始めた当初は、そのすさまじい実装の速さに「エンジニアの役割はどうなるのか」と正直焦りを感じていました。
しかし読み終えて思うのは、エンジニアの仕事はなくなるのではなく、「どういう仕様で進めるか」という意思決定を知見として残すことに比重が移るのだということです。
実装が速くなるからこそ、プロダクトの背景や歴史、一つひとつの機能の意図を丁寧に言語化し、AIに正しく伝える力がこれまで以上に重要になると感じています。
「モグラ叩き」から学んだスペック駆動の価値
ただAIに任せるだけでは、スピードは上がりません。実際、仕様を詰めずにAIに指示を出したことで、直すたびに別のバグが出てくる「モグラ叩き」のような状態にも陥りました。
そこで活きてくるのが、本書で学んだ「スペック駆動開発」という手法です。
- ステアリング：実装前にドキュメントやTODOを整理し、AIの進む道を定義する。
- コンテキスト管理：
/clearなどを使い分け、AIに渡す情報を整理し続ける。
こうした「急がば回れ」の管理こそが、結果的に開発のスピードを上げるのだと、身をもって学びました。
ヘッドレスモードと「計測」という観点
対話なしで自動実行する「ヘッドレスモード」についても、単なる効率化以上の発見がありました。
途中でユーザーが介在できない分、事前のドキュメント作りがいかに重要かを痛感しました。さらに、出力されたメタデータから「実行時間」や「トークン使用量」を見てワークフローを改善できる。こうした数字で振り返る視点を得られたのも大きな収穫です。
既存プロダクトでの実践
本書の例は「新規開発」がメインでしたが、私たちの現実は「既存プロダクトへの機能追加や修正」が主戦場です。
今回学んだ手法を、複雑な既存コードにどう当てはめていくか。まずは個人で使い倒して得た知見を展開し、チームの標準にしていければと考えています。
実装から「足場づくり」へのシフト 井田
「直す」から「設計する」へ
この1年を振り返ると、開発体験は大きく変わりました。これまでは「AIの書いたコードを人間が直す」という感覚でしたが、今は「AIが正しく動くための足場を設計する」ことが重要だと考えています。
学びの中で一番響いたのは、ドキュメントがAIの精度に直結するという点です。これまで開発が途中で頓挫したり、AIが迷走したりしていた原因は、AIの「情報の揮発」にありました。.steering/ に仕様やタスクを外部メモリとして残すことで、複雑な実装でも最後まで精度を保って完結できるようになったと実感しています。
目的を持って学び続ける
AI主導の開発を進める中では、失敗も危機感もあり、同時に未来へのワクワクも感じています。
ただ、変化し続けるAIの動向をすべて追いかけようとすると、正直なところ疲れてきます。だからこそ大事にしたいのは、好奇心を持ちつつ、目的から学ぶ対象を選ぶことです。
あくまで「何かを作るために学ぶ」のであって、学ぶこと自体が目的にすり替わらないようにしたい。新しいツールや手法に振り回されるのではなく、自分が作りたいものを軸に、必要な学びを取りに行く。そんなスタンスで、これからもAIと付き合っていきたいです。
まとめ：読書会で最も白熱した議論
短い期間で駆け抜けた今回の読書会ですが、最後の振り返りでは以下のようなテーマが盛り上がりました。
- AIによって変わる、エンジニアの役割や働き方の変化
- スペック駆動開発やAIを使ったドキュメント整備を、チームとしてどう運用させていくか
スペック駆動開発を実際に試す中で、その効果も、これから向き合うべき課題も見えてきました。読書会を通して得た共通認識をチームの取り組みへ広げていく必要性を感じています。
今後も状況を見ながら、こうした学びの場を続けていきたいと思います。
