DECISIONS — 運用ルールの根拠
運用ルールそのものは README にある。ここに置くのはその根拠、つまり 結論だけ見ても理由が分からないものと、うまくいかなかった結果。
判断基準: 結論から理由が推測できるなら、ここには書かない。 README に一行書けば足りる。
| # | 決めたこと | 状態 |
|---|---|---|
| 1 | url は英語版を正とする。ただし読むのは日本語版でよい | current |
| 2 | whats-new の最新エントリ確認は自動化しない | current |
| 3 | digest は再取得のトリガーにのみ使い、記述の根拠にしない | current |
| 4 | 時系列リストのページは「最上位N件」を明示して取得する | current |
| 5 | 原典側の欠番は明記して、自分の取りこぼしと区別する | current |
| 6 | 鮮度チェックは月1回。fetched の90日閾値だけに頼らない | current |
| 7 | 引用は英文を残して訳を併記する（置き換えない） | current |
| 8 | 要約に言い換える前に、原文を引用として残す | current |
1. url は英語版を正とする。ただし読むのは日本語版でよい
状態: current ／ 実測日 2026-08-10
決定: frontmatter の url は英語版、url_ja を併記。普段は ja を読み、コマンドやフラグを打つ前と、説明が腑に落ちないときだけ en を見る。
却下した当初の理由: 「日本語版はページ数が少ない」「翻訳が遅れる」。どちらも実測で否定された。
platform.claude.com/llms.txt の「English 553 pages / 非英語 各201 pages」という記述を根拠に「日本語版はサブセット」と判断していたが、実際のページ到達性はこれと一致しなかった。201 が何を数えているかは不明。
実測した内容
code.claude.com22本 +platform.claude.com21本について/docs/en/<path>と/docs/ja/<path>の HTTP ステータスを比較- 存在しないパスで対照実験（silent fallback で 200 を返していないかの確認）
code.claude.com/docs/{en,ja}/best-practicesの本文を突き合わせ- Engineering ブログの ja 版の有無を確認
| 論点 | 結果 |
|---|---|
| カバレッジ | **問題なし。**43ページすべて ja が 200。存在しないパスは en/ja とも 404 なので偽の 200 ではない。API リファレンスや管理系（api/errors、manage-claude/compliance-api、wif-providers/okta）まで翻訳済み |
| 鮮度 | 問題なし。best-practices の ja / en はセクション構成が完全一致。/goal、Stop hook、auto mode、agent teams、/btw、/rewind、checkpointing、adversarial review、/code-review もすべて ja にある |
| 翻訳の欠落 | **これが唯一の実問題。**構成は同じでも、具体的なコマンド・フラグ・条件が ja で落ちる |
欠落の実例（すべて best-practices ページ内）
| # | en | ja | 深刻度 |
|---|---|---|---|
| 1 | 「Shift+Tab を ⏸ plan mode on が出るまで押す、または claude --permission-mode plan で開始」 | 「Plan Mode に入ります。」のみ | 入り方が分からない |
| 2 | plan mode を出るのは「プラン承認 or Shift+Tab」 | 「Plan Mode を終了し」のみ | 中 |
| 3 | claude mcp add --transport http notion https://mcp.notion.com/mcp | 実例なし | 中 |
| 4 | 出力3形式の違いの説明段落（json は result フィールドを持つ単一オブジェクト、stream-json は1行1オブジェクトで init イベントから始まる） | 段落ごと欠落 | 中 |
| 5 | 「移行対象ファイルをファイルに書き出させる。... and save the list to files.txt」 | 「リストさせます」のみ | 例が壊れている。次ステップの cat files.txt が宙に浮く |
| 6 | 「checkpoint が追跡するのは Claude のファイル編集ツール経由の変更のみ」 | 「Claude が行った変更のみを追跡します」 | 限定が消え、直後の Bash の但し書きと繋がらない |
| 7 | 「[brief description] を自分の機能に置き換えてから送れ」 | 欠落 | 低 |
| 8 | ”run Claude non-interactively, without an interactive prompt” | 「セッションなしで非対話的に実行できます」 | 誤訳。直後の「実行は再開可能なセッションを作成します」と矛盾する |
リンクのアンカーが食い違う箇所もあった（en checkpointing#rewind-and-summarize ／ ja checkpointing#restore-vs-summarize）。
#1 #5 #6 #8 はいずれも、ja だけを読んでいたら詰まるか間違える箇所だった。 これが「読むのは ja でよいが、打つ前に en を見る」という中途半端に見えるルールの理由。
Engineering ブログに日本語版は存在しない（anthropic.com/ja/engineering/... も anthropic.com/engineering/ja/... も 404）。選択の余地なし。
教訓: 索引ファイルのメタ情報を根拠に判断し、実測しなかったのが誤りだった。「〜のはずだ」で1文書くより、curl を43回叩くほうが速くて正しい。
再検討の条件: 翻訳の欠落が解消されたと確認できたとき。確認は best-practices の ja / en 本文突き合わせで足りる。
関連: claude-code-best-practices ／ agent-skills-best-practices
2. whats-new の最新エントリ確認は自動化しない
状態: current ／ 発覚日 2026-08-12
決定: scripts/freshness-check.sh の step 4 は手動確認を促すだけにする。スクリプトに判定させない。
根拠: 鮮度チェックの起点そのものが古くなっていたから。
2026-08-10 に whats-new を取得したとき、最新エントリは W29（7/13–17） だった。2026-08-12 に取り直すと W30（7/20–24）と W32（8/3–7） が現れた。W30 は7月下旬、W32 は8月上旬の内容なので、8/10 時点で既に公開されていたはず。つまり「2日で増えた」のではなく、初回取得が不完全だった。
sources/whats-new.md は鮮度チェックの起点として置いた文書である。その起点が古いと「最新は W29 だから自分の sources/ は最新」と誤判定する。基準点が壊れているとチェック全体が無意味になる。
同じ失敗を自動化で固定してしまわないよう、step 4 だけは人間が原典の最上部を見る。
あわせて whats-new.md に書き足した警告:
このページ自体の取得に注意: このページのスナップショットは「取得できた範囲」であって「存在する全部」ではない可能性がある。鮮度チェックのたびに最上部のエントリを直接確認すること。
再検討の条件: 原典側に機械可読な索引（週番号の一覧）ができたとき。
3. digest は再取得のトリガーにのみ使い、記述の根拠にしない
状態: current ／ 検証日 2026-08-12
決定: whats-new のような digest から「何かが変わった」ことは読み取るが、sources/ の記述は必ず原典ページを再取得してから書く。
根拠（当初）: README の「WebFetch などで原典を実際に取得してから書く。記憶で書かない」に従うと、digest の要約文は二次情報なので根拠にできない。
根拠（実証された）: 保留していた4ページを実際に取得したところ、digest 経由の情報は3件中2件で言い換えが起きていた。
| ページ | 結果 |
|---|---|
| choosing-a-model | 内容に変化なし。digest の「Opus 5 が Claude Code の既定 Opus モデルに」はこのページに書かれていない。原典が述べているのは「effort の既定が high（Claude Code と Messages API の両方で）」であって、既定モデルの話ではない |
| skills | **変化あり。**ただし digest の「バックグラウンド subagent」は不正確で、原典は forked subagent（v2.1.218 以降）と書いている |
| sub-agents | 変化あり。SendMessage 自体は agent teams を要さず、cross-session messaging が有効なら自分の他セッションにも送れる |
| agent-teams | **変化あり。**mailbox の検証、書き込み失敗時の送信エラー、分類器のチェックがチーム外のセッション間メッセージにも及ぶこと |
digest は「何かが変わった」という信号としては正しかったが、変更の中身は2件で言い換えられていた（既定モデル / 既定 effort、background / forked）。
副産物: この再取得で cross-session-messaging という独立ページの存在が判明した。再取得は差分の反映だけでなく、新しい原典の発見にもなる。
4. 時系列リストのページは「最上位N件」を明示して取得する
状態: current
決定: 件数や最新項目が意味を持つページでは、「ページを要約して」ではなく**「最上位N件を挙げて」と明示的に要求する**。
根拠: 決定2の一般化。ページ全体を要約させる方式は、「取れた分だけ」を「全部」と誤認しうる。
特に危険な形:
- 時系列に長いリスト（changelog、リリースノート、週次 digest）
- 対話的に生成される要素を含むページ（
whats-newは<Update>コンポーネントの列）
2026-08-12 の再取得では「top 3 entries」と指定して取得し、取りこぼしを解消した。
5. 原典側の欠番は明記して、自分の取りこぼしと区別する
状態: current
決定: 原典の索引に欠けがあるとき、sources/ 側に「索引に存在しない」と明記する。
根拠: whats-new の索引が W30 → W32 と飛んでいた。原典側の欠番か未公開かはこちらでは判断できない。
書いておかないと、次に見たとき「また取りこぼしたのか？」と分からなくなる。自分の失敗と原典の状態を、記録の上で区別しておく。
6. 鮮度チェックは月1回。fetched の90日閾値だけに頼らない
状態: current
決定: scripts/freshness-check.sh を月1回回す。
根拠: 変化が速い3領域があり、90日閾値では取り残される。
| 領域 | 変遷 |
|---|---|
| auto mode / permission | W21 導入 → W28 既定化の予告 → W32 展開 |
| subagent の既定挙動 | W24 ネスト解禁 → W26 権限確認 → W27 既定バックグラウンド化 |
| モデルの既定 | W16 Opus 4.7 → W22 Opus 4.8 → W27 Sonnet 5 → W30 Opus 5 |
約2ヶ月に1度、既定モデルが変わっている。 初回取り込みから2日後に回した鮮度チェックで既に修正が必要だったことも、この頻度を裏づける。
7. 引用は英文を残して訳を併記する（置き換えない）
状態: current ／ 決定日 2026-08-12
決定: 原典からの引用は英文をそのまま残し、引用ブロック内の直下に訳を置く。原典の英語タイトル（frontmatter の title、SOURCES.md の記事一覧）は訳さない。
却下した案:
| 案 | 却下の理由 |
|---|---|
| 訳に置き換える | README が「原典と照合しやすさを優先している」と述べている以上、repo 自身の方針に反する。原文で grep できなくなり、誤訳が入っても検出できない |
| 訳を主、原文を括弧で従 | 長い引用で括弧が肥大する。「引用」なのに訳が主になる |
| 意味のある箇所だけ訳す | 基準が主観的になり、読み手が「なぜここだけ訳がないのか」と迷う |
判明した事実: 未訳の英文を検出したところ 522箇所あったが、うち 88箇所は原典の英語タイトルだった。これは文章ではなく原典を検索・特定するための固有名なので訳す対象ではない。訳したのは引用 434ブロック。
強制の仕組み: scripts/freshness-check.sh の step 5 が、連続する引用ブロックのうち英文だけで日本語を含まないものを検出して exit 1 する。方針を文章で書くだけでなく検査を置いたのは、規約は破られたときに気づけないと意味がないから。
8. 要約に言い換える前に、原文を引用として残す
状態: current ／ 発覚日 2026-08-13
決定: sources/ では、要点を日本語で書く前に原文を引用として置く。日本語要約だけのファイルを作らない。
根拠: 引用を1つも持たないファイルが実在し、そこで照合が効かなくなっていた。
sources/building-effective-agents.md は、この分野の出発点とされる文書でありながら
英文引用が1つもなく、日本語の要約だけだった。そのため次の2つが起きた。
- 原典に何と書いてあるかを確認できない。 「Claude is already smart のような一文はあるか」という 問いに、リポジトリ内だけでは答えられなかった（再取得して初めて存在しないと確定した）
- 引用が言い換えられていた。
topics/agent-design.mdにはFind the simplest solution possible, and only increase complexity when needed.とあったが、 原文はWhen building applications with LLMs, we recommend **finding** the simplest solution possible, and only **increasing** complexity when needed.である。命令形に直されていた
同じことが claude-prompting-best-practices でも起きていた。
Claude is smart enough to generalize from the explanation. という一文が、
「指示の背後にある動機を説明すると、Claude はそこから一般化する」という日本語の言い換えだけになっていた。
なぜ危ないか: 言い換えは一見すると正しく、検査にもかからない。訳漏れ検査（決定7）は 「英文があるのに訳がない」ことしか見ないので、そもそも英文を置かなければ何も検出されない。
運用への反映:
_TEMPLATE.mdの「要点」に、主要な主張は引用で置くことを明記した- 引用を書くときは原文をコピーする。手で打ち直すと今回のように活用が変わる
- 「この文書の代表的な一文は何か」を答えられないファイルは、要約が薄いのではなく引用が無い
例外: 索引・カタログ・設定リファレンス（settings / hooks / use-case-guides /
claude-cookbooks / prompt-library）は、引用すべき地の文をほとんど持たない。
ここでの対象は主張を述べている文書である。
副次的に見つかった検査の穴: scripts/freshness-check.sh の step 3（wikilink）は
壊れたリンクを表示するだけで exit 1 していなかった。QUOTES.md を再生成したときに
壊れたリンクが復活したのに、チェックは通ってしまった。fail=1 を立てるよう修正した。
「表示する」と「失敗させる」は別物で、後者でなければ自動検査の意味がない。