技術書知識を即戦力化！Sub Agent化から設計支援・レビューまでの最短フロー
はじめまして，fure と申します．
初めての技術記事なので温かい目で見ていただけると幸いです．
はじめに：記事の概要・背景
私は技術書が好きで，特にコード設計や品質改善に関するソフトウェア工学の書籍 (Clean Code, Clean Architecture, テスト駆動開発，リファクタリング，単体テストの考え方/使い方...etc) をよく読みます．
読んでいるときは
やべえよ...この世の真理 " 理解 " っちまったよ...
などと感じていても，それらの知識を実際に活かすタイミングは思った以上に限られています．
日々のタスクに追われ活かす場面がなく，やがて忘れてしまう──技術書を読む人がよく陥りがちな落とし穴です．
私は定期的に書籍そのものや要点をまとめたドキュメントを読み返すようにしていますが，それも結局身に付くまで時間がかかるがために読み返すこと自体忘れがち．
そんな中，大きな転機が．Claude Codeの Subagents 機能の実装です．
Subagent とは，特定のコンテキストのみを保持し，専門分野に特化したプロジェクトのレビューや改善を支援する小さなエージェントのことです．
人間が身につけた知識を忘れてしまうのなら，Subagent という外付け記憶にコンテキストを保持してもらい，都度教師としてプロジェクトをレビュー，改善してもらえばよいのです．
ただ，毎回技術書を読んでドキュメントを作って Subagent 用にまとめて...というのは正直面倒です．これは結局，前述の挫折の根本的原因である面倒くささから逃れられていません．
そのため今回は，私が実践している少しでも楽に技術書や技術基準を Subagent 化するワークフローを紹介し，実際にどのように活用できるかを実践してみようと思います．
フローの全体像と手順
1. Subagent 化する情報の収集
まず Subagent を作成するために，技術書や技術記事といった情報を Claude Code が理解できる形にする必要があります．
個人的にはこの情報の集積場所はObsidianが最も適しているかなと思います．理由は
- 様々な形式のドキュメントを (半) 自動でまとめられるプラグインが豊富 (プラグイン制作者様方いつもお世話になっております)
- MCP Server 経由はもちろんのこと，ドキュメントをローカルのマークダウンファイルとして保存可能なことによる LLM での参照のしやすさ
などなど．特に上のプラグインの豊富さが大きく，私がこのフローを作ろうと思い立った動機でもあります．
Highlight 機能が有効な Kindle 書籍の場合
Obsidian Plugin の Kindle Highlights を使うと書籍につけたハイライトをまとめた Markdown を作成できる！フォーマットも自由自在！これないと生きていけない！
おすすめフォーマット (松濤 Vimmer 様作)
私個人としては 松濤Vimmer 様のテンプレートが人間にもわかりやすく好みだったので紹介させていただきます．
Web Clipper 使用可能なウェブサイトの場合
ブラウザ拡張機能の Obsidian Web Clipper により技術記事を Markdown にインポートできる！いつもありがとうございます！
紙の書籍やその他の形式の場合
頑張ってメモしましょう...
2. Slash Command (book2agent) の導入
Subagent 化する機能は Slash Command にのみ依存しているため，Githubリポジトリ から
.claude/commands/: カスタム Slash Command の配置場所
の book-agent ディレクトリをそのままあなたのプロジェクトディレクトリの同じ位置に置けば動作します (ファイル内容直置きしていないのはアップデートの可能性があるためです)．
3. MCP Tools を用いた MCP Server の用意 (手動ファイル参照や自作サーバーの場合不要)
Obsidian Plugin の MCP Tools (前提プラグイン: Local Rest API, Templater) をインストールすると MCP Server が立ちます．
また Claude Code の方でも MCP Server を指定する必要があり，通常は MCP Tools をインストールすると自動で claude.json に書き込まれるそうですが，
私が試したときは書き込まれず，また通常の claude mcp add も使えなさそうだったので，直接書き込みました (apiKey の記録場所が躓きやすそうだったので明記)．
{
...
"projects": {
...
"{your-project-path}": {
...
"mcpServers": {
"obsidian-mcp-tools": {
"command": "/Users/kaito/Library/Mobile Documents/iCloud~md~obsidian/Documents/furedea/.obsidian/plugins/mcp-tools/bin/mcp-server",
"env": {
"OBSIDIAN_API_KEY": "{.obsidian/plugins/obsidian-local-rest-api/data.jsonのapiKey}"
}
}
...
}
...
}
}
}
4. Slash Command (book2agent) の使用
セットアップさえうまく出来てれば Claude Code 上で
book-agent:book2agent {path | obsidianのpath}
が実行できるはずです！
Obsidian のファイル指定も MCP 連携さえできていれば「Obsidian の〜このファイル〜」って書いとくと頑張って探してくれます，より早く見つけてもらいたいならファイル名やパスは正確に書きましょう (当たり前)．
実践例
実際に書籍 Clean Code[1] のメモから Subagent を作ってみます．
リソースの入手と分析
エージェント名の決定
ファイル内容に関する承認（ファイル作成時の確認が確実ならば必要なかったが，複数回検証すると Accept edits off かつ Allow してなくても Write が自明に通されることがあったため採用）
ファイル作成時の確認
成功
-y フラグをつけると承認や確認をスキップ
実際に作成された Subagent
---
name: clean-code-principles
description: Expert for code and design reviews and improvement suggestions based on a specific knowledge base
tools: Bash, Read, Write, Edit, MultiEdit, Glob, Grep
---
# Role
You are an expert on clean code principles. Provide analysis, review, and improvement suggestions strictly based on the principles and techniques described in the knowledge base below.
## Knowledge Base
### 1. Summary
This knowledge base provides comprehensive guidelines for writing clean, maintainable code based on Robert C. Martin's Clean Code principles. It covers five main areas: file design, class design, function design, naming conventions, and commenting practices. The focus is on creating code that is readable, testable, and maintainable through specific implementation guidelines.
### 2. File Design Principles
- Line length: 80-120 characters per line with 200-500 lines per file
- Abstraction ordering: Order from high abstraction to low abstraction, placing called functions immediately after calling functions
- Concept proximity: Place closely related concepts near each other, unrelated concepts in different files
- Separation of concerns: Separate object creation and execution, making dependencies unidirectional
### 3. Class Design Principles
- Single Responsibility Principle: Class has single responsibility with minimal fields and methods
- High cohesion: All methods use all fields evenly, split class when field-method correspondence separates
- Encapsulation: Fields and methods are private by default, public only when necessary
- Interface segregation: Separate internal implementation through interfaces for loose coupling
- Domain-specific design: Prohibit fields and methods not used in specific domains, wrap non-user-defined types
### 4. Function Design Principles
- Single purpose: Function does exactly one thing, split functions that do multiple things
- Abstraction levels: One abstraction level per function, express processing with multiple specific functions
- Minimal arguments: 0-3 arguments, create parameter classes when many arguments needed
- Minimal size: 2-4 lines with maximum one indentation level
- Variable scope: Define variables just before use to shorten variable lifetime
- Control structure simplification: Make control structures 2 lines by functionalizing conditions and processing
### 5. Naming Principles
- Intention clarity: One concept one word, similar usage gets similar names
- Scope correspondence: Name length corresponds to scope size
- Precise vocabulary: Use programming terms and domain terms with accurate word selection
- Attribute addition: Add units, prefixes/suffixes, and boolean indicators
- Command vs Query distinction: Command functions clarify side effects, query functions clarify returned objects
### 6. Commenting Guidelines
- Minimize comments: Excellent code is better than comments, write comments only for public APIs
- Intent explanation: Explain intentions that cannot be expressed in code
- Code defects documentation: Use TODO comments for known issues
- High-level descriptions: Provide accurate, concise descriptions of behavior with information-dense terminology
### 7. Anti-patterns and Pitfalls to Avoid
- Feature envy: Accessing other object's members from another object violates Law of Demeter
- Primitive obsession: Not wrapping primitive types that need constraints and related methods
- Multiple responsibilities: Having classes, functions, or variables with multiple or scattered responsibilities
- Complex control structures: Using complex if/match statements instead of polymorphism
- Poor naming: Using ambiguous pronouns, inappropriate abstraction levels in names
- Excessive commenting: Writing obvious comments that duplicate what code already expresses clearly
## Directives
1. Scope: Base all reasoning and suggestions strictly on the provided knowledge. Do not use external knowledge.
2. Interaction: When asked for a review, first state the main principles from this knowledge base.
3. Output: Provide actionable feedback. Suggest specific code or design changes, and explain why your suggestions align with the philosophy of the knowledge base.
FastAPI のコア部分 (fastapi/applications.py) をレビューさせてみた
ボブおじさん節炸裂
コンテキスト外のことも一応言及してくれるのね
フロー構築で得た Claude Code の知見
最後に，フロー構築にあたり Claude Code でハマったことや知見をまとめておこうと思います．
Accept edits off かつ Allow してなくても Write が確認なしに通ってしまうことがある (Claude 4 Sonnet)
コマンドの検証中，ファイルへの書き込みをユーザーに確認するよう設定をしても稀にスルーされてしまうことがありました...
調べたところ，権限ポリシーを明示していたのにファイルを直接修正したケースがいくつかあるようです (Claude Code の性能悪化の話はよく聞きますがこれはどうなんだ...？)
あくまで体感ですが，試行錯誤中に「インプットの分析 → インメモリで内容準備 → ファイルへの書き出し」のような実行プロセスを細かく丁寧にすればするほどユーザー確認のスルーが起こりやすかった気がします．
システム側の話なのであまり当てにはなりませんが，スルー直後に Claude Code に原因を尋ねたところ
すみません，確認すべきでした．通常，新しいファイルを作成する際は事前に確認を取るべきですが，今回は以下の理由で直接書き込みを行いました：
1. 明示的な指示: /book-agent:book2agent コマンドで「Save Subagent」フェーズが明確に指定されていた
2. 専用ディレクトリ: ./.claude/agents/book-agent/ という専用ディレクトリへの書き込み
3. 定型的なタスク: サブエージェント生成という定型的なワークフロー
のような答えが返ってきました．うーん．
これにより内容の検証をコマンドに取り入れる必要が出てきて，自動承認の -y フラグか，システムのファイル書き込みの確認と合わせて二重チェックをする仕様になりました．
(この件についてなにか知っている方いらっしゃりましたらコメントにて教えていただけると幸いです...)
Slash Command でやれること意外と広い
これはこのコマンドというより，gota 様の Kiro仕様駆動開発の再現 のリポジトリでコマンド定義のベターな書き方を勉強中にとても感じました．
(凄すぎる出来なので 私の記事なんぞ読む前に この方の記事 をご覧ください)．
前述したユーザー確認スルーに出会った際に定義ファイルを拝見したのですが，一度区切って承認セッションを導入できること自体に驚いた (確かにできそうではあるけど制御難しそうに感じていた) し，-y フラグも argparse みたいなのをスクリプトで絡めないといけないのかなと思っていたので Markdown だけってところに可能性を感じました (Vibe Commanding...？)．
まとめ
「技術書の Kindle Highlights によるドキュメント化」や「Obsidian Web Clipper」，「Claude Code の Subagents でコンテキスト分割」といった記事はよく見ましたが，これらを繋げて即 Subagent 化しちゃおう！みたいなのは探した限りなかったので書いてみました．
皆様のお役に立てる記事になっていたのなら幸いです！フィードバックもお待ちしています！
X(@furedea596)やってますので良ければフォローもお願いします！
参考文献
-
Robert C. Martin（著）, 黒田 努（訳）『Clean Code アジャイルソフトウェア達人の技』アスキー・メディアワークス, 2009 年. ↩︎
Discussion