YAML のクォートなしの文字列（プレーンスカラー）には、コロンの直後に空白が続く : を含められません。YAML 1.2.2 の仕様がそう定めていて、フロントマターの title: に キー名: 値 の形をそのまま入れると、YAML として読めなくなります1。

社内の記録スクリプト（決定・学び・メモを1件ずつ Markdown ファイルとして作るもの）にこの形のタイトルを渡すと、YAML が壊れて作成に失敗し、生成直後のファイルが自動で削除されました。最初の失敗（2026年8月30日）のあと、学び記録に「タイトルにキー名や設定値をそのまま書かない」と残しました。ところが同じエラーは、調べた範囲でその後さらに2回、16日後（9月15日）と25日後（9月24日）に起きています。3回とも実行したのは Claude Code です。

再発した2回のセッションでは、失敗の前にその学び記録がセッションに現れた行は0件でした。同じ入力が試験で通るようになったのは、記録を読ませたからではなく、台帳のテンプレートの title をクォートした時です。修理後の運用は調べた記録の範囲外なので、再発が止んだかどうかは分かりません。

1回目の事故で、記録に残したのは「避け方」だった

2026年8月30日、Claude Code が記録スクリプトを呼びました。タイトルは、たとえば 決定の題名（tags: [x]・recall: y） のように、キー名: 値 の形を含むものでした。

エラー文は YAML error: mapping values are not allowed in this context at line 2 column 24 で、続けてスクリプトが「adrs new が失敗したため、生成直後の残置ファイルを削除した」と表示しました。adrs は ADR（アーキテクチャ決定記録）を管理する CLI で、記録スクリプトはこの adrs new でファイルを作ります。

回復は、コロンを除いたタイトルでの再実行でした。学び記録には、含意として「タイトルにキー名や設定値をそのまま書かない」と書きました。この時点で、スクリプトもテンプレートも変えていません。

当時は、エラー文がその場で見えていて、生成直後のファイルが削除されたことも表示され、原因もタイトルの書き方にあるように見えました。それなら「書き方の規約」として学び記録に残すのが自然に思えたのです。

16日後と25日後にも同じエラーが出た：YAML のタイトルでコロンが壊すのはどの形か

2回目は9月15日、初回の16日後です。タイトルに verified: を含む形で、エラー文は同じ mapping values are not allowed in this context（column 30）でした。Claude Code は直後に「タイトルの : で YAML が壊れたので直します。」と述べ、コロンを外したタイトルで再実行して成功しました。

3回目は9月24日、25日後です。タイトルに 題名の一部: 続き のようにコロンと空白を含む日本語の題名で、エラー文は同じ（column 20）でした。再実行は、タイトルからコロンを外して成功しています。

3回とも実行者は Claude Code の呼び出し（tool_use）で、人が ! で手打ちした実行の記録は3セッションとも0件でした。エラー文は同じで、桁の数字だけがタイトルごとに違います（24・30・20）。学び記録には、2回目（9月15日）の記載がありません。

試した3種の入力のうち、壊れたのはコロンの直後に空白が続く形だけでした。次の表は、修理前のテンプレートで adrs new にタイトルだけを変えて通した結果です。

入力（タイトル）結果理由
A:B通るコロンの直後が空白ではない
A：B（全角コロン）通る全角コロンは YAML の記号ではない
A: B失敗コロンの直後に空白が続く

実測は入力ごとの通る・失敗だけで、理由の欄は YAML 仕様に基づく解説です。仕様（7.3.3 Plain Style）は次のように定めています1。

Plain scalars must never contain the “: ” and “ #” character combinations. Such combinations would cause ambiguity with mapping key/value pairs and comments.

: （コロンと空白）と #（空白とハッシュ）は、マッピングのキーと値、およびコメントと区別がつかなくなるため、プレーンスカラーに含められない、という意味です。エラー文言 mapping values are not allowed in this context は仕様には書かれていません。仕様が禁じ、パーサーがこのエラーで拒否する、という分担です。今回試したのは上の3種だけなので、 # を含むタイトルの挙動は実測していません。

学び記録は、失敗の前にセッションに現れなかった

調べたのは、同じエラー文を含むセッション3本（1回目・2回目・3回目の各セッション）です。あるプロジェクトのセッションに限ります。

1回目のセッションは、学び記録が失敗の後に作られたので、失敗の前に現れないのは当然で、証拠になりません。「失敗の前に記録が現れたか」を問えるのは、記録がすでにあった2回目と3回目の2セッションです。この2本とも、学び記録への言及（記録の識別子・ファイル名の断片のいずれか）が失敗の前に現れた行は0件でした。

セッション失敗より前に記録が現れた行記録が最初に現れた位置
1回目（8月30日）対象外（記録は失敗の後に作られた）失敗の後、記録を作る呼び出し
2回目（9月15日）0件セッション全体で0件
3回目（9月24日）0件失敗の後、原因を調べる過程

3回目のセッションでは、Claude Code が失敗の後に git の履歴を調べる過程で記録を見つけ、「前にも同じ問題を記録していました」と述べています。

この集計の母数は2セッションです。「現れた」は、セッションの記録（jsonl）を、学び記録の識別子とファイル名の断片で検索した結果なので、検索の語に限った不在の主張になります。「記録が読まれていれば防げた」とは言えません。2回目のセッションで Claude Code の文脈に何が入っていたかは、記録からは特定できないためです。

Claude Code の公式ドキュメントは、起動時に読まれるものと、必要に応じて読まれるものを区別しています。起動時に読まれるのは CLAUDE.md と、MEMORY.md の先頭200行（または25KB のどちらか先に達したほう）です。トピックファイルは起動時には読まれず、必要になったときに Claude が読みます。サブディレクトリのファイルも、そのディレクトリのファイルを読んだときに読まれます2。公式ドキュメントは台帳という置き場には触れていないので、自分の記録がどちらに当たるかは、読者が自分の環境で点検することになります。

私は、避け方を学び記録に書いただけでは、使う場面（エージェントが次にスクリプトを呼ぶ時）でその記録が読まれる保証はないと考えています。避け方を書くときは、同じ記録に「環境側で直せるか」を1行添えることを勧めます。

壊れた場所と、守っていた場所がずれていた

記録スクリプトには、タイトルを JSON 形式の文字列に直してクォートする処理が実在していました。ただしその処理は、YAML ファイルを作る adrs new の呼び出しより後に走ります。adrs new が失敗すると、スクリプトは残ったファイルを削除して終了し、クォートの処理には到達しません。この順序は、手元にある過去の全ての版のスクリプトで同じでした。

一方、adrs に渡すテンプレートは、決定・学び・メモの3台帳とも title: {{ title }}（クォートなし）でした。エラー文には Error: Failed to update ADR status も含まれていて、adrs new が status を更新する段階で YAML を解析できなかったと読めます。

adrs 本体の組み込みテンプレートも同じ形です。2026年9月29日時点の main では、4か所が title: {{ title }} のクォートなしで、ソースのテストのコメントには「A bare title: {{ title }} breaks as soon as the title carries a colon, a leading quote, or a #」と書かれています3。

予防の処理が実在していても、守っている場所が、実際に壊れる場所とずれることがあります。守る処理と壊れる処理の実行順序は、点検する価値があります。

テンプレートの title をクォートする：同じ入力が通るようになった1行の修理

修理は、決定・学び・メモの3台帳それぞれのテンプレートの1行でした。目的は、テンプレートがタイトルを JSON の文字列として出力し、コロン・引用符・# を含んでも YAML として壊れない形にすることです。

ファイル: 各台帳の template.md（3ファイルとも同じ1行の変更）

-title: {{ title }}
+title: {{ title | tojson }}

修理後、3台帳を、通常のタイトル・コロンと引用符を含むタイトル・--supersedes（既存レコードを置き換える指定）付きの3系で試験し、全て通りました。

tojson は minijinja（adrs が使うテンプレートエンジン）のフィルタで、値を JSON にします。json feature が有効なときだけ使えます4。minijinja のドキュメントに YAML への言及はありません。

adrs の Issue では、同じ {{ title | tojson }} が、カスタムテンプレートでタイトルをクォートする方法として提案され、「JSON の文字列は有効な YAML で、そのまま往復できる」とされています5。この提案を受けて、adrs 側で minijinja の json feature を有効にする変更が2026年9月3日に取り込まれました6。この feature が無効なまま tojson を使うと、Template error: unknown filter: filter tojson is unknown になります5。

試験には落とし穴が2つありました。

  • 試験に使う入力は、壊れる形そのものにする必要があります。A:B のようなコロンの後ろに空白がない形は壊れないので、壊れを検出できません。壊れる形は A: B でした。
  • 試験の環境変数（記録の置き場所を指す変数）が設定されたまま、試験用のディレクトリに移動していました。そのため --supersedes の試験が、本物の台帳のレコード1件の status を書き換えました。未コミットのうちに戻し、環境変数を外して3台帳を試験し直しています。

この修理で直らないことと、避け方の記録が効く場面

直るのは、タイトルのクォートだけです。本文やタグなど、ほかのフィールドに同種の入力が渡る場合は、別の対処が要ります。

「避け方の記録は無駄だったのか」という反論があるでしょう。3回とも失敗の前に現れなかった、という範囲でしか言えません。人が読む運用メモとしては、有効な場面があります。環境側で直せないとき、たとえば外部ツールの仕様に起因するときや他人のリポジトリのときは、避け方の記録が唯一の手段になります。注意書きを足し続ける設計そのものの限界は、AIパイプライン運用における「振り返り」の設計論で書きました。

「Claude Code が読んでいれば防げたのでは」という反論には、未検証と答えるしかありません。記録から言えるのは、失敗の前に現れなかったところまでです。

「クォートの実装がスクリプトにあったのだから十分では」という反論は、その実装が壊れる地点に届く場所にあったか、という問いになります。今回は届いていませんでした。

前提が変われば結論はどう変わるか

学び記録が、起動時に読まれる場所（CLAUDE.md や、MEMORY.md の先頭200行または25KB）にあれば、失敗の前に現れた可能性はあります2。ただしその領域は有限で、全ての学びは置けません。実際にそうなったかは、今回の記録からは確かめていません。

記録スクリプトの側でタイトルを先にクォートする、または呼び出し側で入力を検証するなら、記録が読まれるかどうかに依存しません。これは一般的な設計の説明で、今回の実測ではありません。

adrs ではなく別のツールで記録を作るなら、そのツールの組み込みテンプレートがタイトルをクォートするかを確認します。adrs の組み込みテンプレートは、2026年9月29日時点でクォートなしのままです3。

よくある質問（FAQ）

Q. YAML のタイトルにコロンを入れると「mapping values are not allowed in this context」になるのはなぜですか？

A. クォートなしの文字列に : （コロンと空白）を含めることを、YAML 1.2.2 が禁じているためです。マッピングのキーと値と区別がつかなくなります。エラー文言はパーサー側のものです1。社内の試験では、試した3種のうち A:B と全角の A：B は通り、A: B だけが失敗しました。仕様は # も禁じています。

Q. テンプレートで生成する YAML の title を安全にクォートするには？

A. テンプレートの title を JSON の文字列として出力します。minijinja では title: {{ title | tojson }} とし、json feature の有効化が要ります4。adrs の Issue では、この方法が有効な YAML として往復できるとされています5。社内の3台帳では、この1行の変更で試験が全て通りました。

Q. 事故の学びを記録しても同じ失敗が再発するのはなぜですか？

A. 今回は、記録がすでにあった2回目と3回目の両方で、失敗の前にその記録がセッションに現れませんでした。「読まれていれば防げた」とまでは言えません。避け方を書くときは、同じ記録に「環境側で直せるか」を1行添えるとよい、というのが私の考えです。

まとめ

  • 学び記録に避け方を残しても、同じエラーは調べた範囲で16日後と25日後に2回起きました（母数は、同じエラー文を含む3セッション）。
  • 記録がすでにあった2回目と3回目の2セッションでは、失敗の前に記録がセッションに現れた行は0件でした。検索の語に限った不在の主張で、1回目は記録が失敗の後に作られたので対象外です。
  • 試した入力のうち壊れたのは : （コロンと空白）の形だけで、A:B と全角の A：B は通りました。仕様は # も禁じているので、試験にはこの形も含めるとよいでしょう。
  • クォートの実装があっても、壊れる地点の後で走れば守れません。守る処理と壊れる処理の順序を点検します。
  • 同じ入力が試験で通るようになったのは、テンプレートの title を JSON 文字列として出力する1行の修理でした。修理は3回目と同じ9月24日で、調べた記録はその時点までです。修理後の再発は観測していません。
  • 避け方を学び記録に残すときは、同じ記録に「環境側で直せるか」を1行添えます。

AI エージェントを実務の仕組みに組み込む際の、記録・自動化パイプラインの点検や仕組み化について、ぜひ コンタクトフォーム よりお気軽にご相談ください。

Footnotes

  1. YAML Ain’t Markup Language (YAML™) revision 1.2.2 YAML Language Development Team、Revision 1.2.2（2021年10月1日）。プレーンスカラーが : と # を含められない規則は 7.3.3 Plain Style。エラー文言 mapping values are not allowed in this context は仕様には無く、パーサー側のもの。 ↩ ↩2 ↩3

  2. How Claude remembers your project Anthropic、Claude Code Docs、2026年9月29日取得。起動時に読まれるもの（CLAUDE.md、MEMORY.md の先頭200行または25KB）と、必要に応じて読まれるもの（トピックファイル、サブディレクトリのファイル）の区別が書かれている。台帳という置き場への言及は無い。 ↩ ↩2

  3. adrs の template.rs（main ブランチ） joshrotenberg/adrs リポジトリ、2026年9月29日時点の main。組み込みテンプレートの4か所（327・364・445・549 行目）が、クォートなしの title: {{ title }}。テストのコメント（1456 行付近）に、コロン・先頭の引用符・# を含むタイトルで壊れるとの記述がある。行番号は main の更新で動く。 ↩ ↩2

  4. tojson in minijinja::filters docs.rs 掲載、2026年9月29日取得（バージョン 2.24.0）。tojson が値を JSON にするフィルタで、json feature が有効なときだけ使えることは、このページの記述による。feature の説明は同クレートのトップページ minijinja - Rust の Features 節。どちらにも YAML への言及は無い。 ↩ ↩2

  5. feat(template): enable minijinja’s json feature so custom templates can use tojson · Issue #384 joshrotenberg/adrs リポジトリ、2026年9月3日に起票・同日クローズ（completed）。title: {{ title }} のカスタムテンプレートが、コロン・先頭の引用符・# を含むタイトルで無効または別の意味の YAML になること、tojson の提案、JSON の文字列が有効な YAML でそのまま往復できるという記述、json feature が無効なときの unknown filter エラーは、Issue の本文に書かれている。 ↩ ↩2 ↩3

  6. feat(template): enable minijinja’s json feature for the tojson filter · Pull Request #386 joshrotenberg/adrs リポジトリ、2026年9月3日にマージ（Issue #384 を Closes）。minijinja の json feature を有効にする変更で、YAML の往復（ラウンドトリップ）で検証している。どのリリースに入ったかは確認していない。 ↩