README

topics/ — 横断統合の「読む層」

複数の原典にまたがる知見を統合して、「結局どうすればいいか」を書く場所。 sources/ が「原典が何を言っているか」なのに対し、ここは「それらを合わせると何が言えるか」。

書き方のルール

各ファイルの冒頭に、どの sources/ を統合したかを必ず明記する。

---
title: コンテキスト設計
synthesizes:
  - effective-context-engineering-for-ai-agents
  - claude-code-best-practices
  - agent-skills-best-practices
updated: YYYY-MM-DD
---

synthesizes があることで、原典が更新されたとき grep で再統合すべき topic を機械的に特定できる。

grep -l 'writing-tools-for-agents' topics/*.md

これがないと、原典が変わるたびに全 topic を読み直すことになる。

いつ書き始めるか

sources/ が10本前後になってから。 原典2〜3本では統合する価値が出ず、sources/ の劣化コピーになる。

→ 2026-08-12 に条件を満たしたので執筆した（sources/ 77本）。

現在のトピック（10本）

トピック	何に答えるか	統合数
context-engineering	context をどう配分するか。何を入れないか	13
agent-design	そもそもエージェントにすべきか。するなら誰に委譲するか	12
tool-design	ツール1本をどう書くか。増えたときどうするか	11
evals	何をどう測るか。eval が壊れる4つの機構	10
prompting	世代をまたいで残る prompting と出力制御	12
model-migration	モデル世代をまたぐとき何を剥がすか	12
claude-code-workflow	いつ何を足すか。日々どう回すか	17
user-config	~/.claude に何を置き、何を置かないか	14
writing-for-agents	エージェントに読ませる文書の書き方	10
security	prompt injection への多層防御	12

1ページの要約は OVERVIEW.md。 こちらは各テーマの深掘り。

意図的に統合していない sources/

次の4本は索引・リファレンス・外部教材であり、統合すると原文の劣化コピーになるので synthesizes に入れていない。

	理由
glossary	用語定義。引くもので、統合するものではない
use-case-guides	4ガイドへの索引
claude-cookbooks	実装レシピへの索引
desktop-extensions	MCP の梱包形式。他テーマと接点が薄い

settings は 2026-08-16 に、この除外リストから外した。 設定キーの一覧としては依然リファレンスだが、スコープの優先順位は単体では使えず、permissions のパス解決・skill と subagent の優先順位の逆転・--bare の非読み込みと噛み合わせて初めて判断材料になる（user-config）。

カバレッジの確認:

./scripts/freshness-check.sh   # wikilink の解決も見る

# どの topic からも参照されていない sources/ を出す
python3 -c "
import re, pathlib
slugs = {p.stem for p in pathlib.Path('sources').glob('*.md')}
ref = set()
for p in pathlib.Path('topics').glob('*.md'):
    if p.stem == 'README': continue
    m = re.search(r'^synthesizes:\n((?:  - .+\n)+)', p.read_text(), re.M)
    ref |= set(re.findall(r'  - (.+)', m.group(1)))
print(sorted(slugs - ref))
"

更新するとき

原典が更新されたら、synthesizes を grep して該当 topic を特定する。

grep -l 'writing-tools-for-agents' topics/*.md

topic を直したら updated: を今日の日付にする。