混乱してきたにゃ（でもちゃんと結果は出たにゃ）- AGENTS.mdの書き方実験

はじめに - AIの気持ちになって考える

ここ数日、AGENTS.md をどのように書くのが良いのか、AIの気持ちになってずっと考えている。

AIは自身がどのように判断したのか（CoT: Chain of Thought）を示すことはできないので、推測するしかないのだが。「やるべきこと」と「やるべきではないこと」を明確に、しかも人間が見てもAIが見ても誤解がないようにするにはどうすれば良いのか？

わかりやすい言葉を探すのに先人の知恵を借りようと、RFCにまで手を出した。これは、私がAGENTS.mdを仕様書として認識しているから。

RFC 2119: Key words for use in RFCs to Indicate Requirement Levels

In many standards track documents several words are used to signify the requirements in the specification. These words …

IETF Datatracker

仕様書は難しいものです。やるべきこととやらざるべきことを表現するために、MUSTとMUST NOTを使って実験してみることにした。

実験1: 単なる羅列の場合

最初の実験は、特別な分類をせずに、やるべきことを単純に並べる形式です。

単なる羅列の場合の実験結果

1
2
3
4
5


This is a pen
日本語に翻訳して
ただし、次に示す内容を厳守すること
- 語尾に「にゃ」をつけること
- 語尾に「にゃ」をつけないこと

指示が矛盾しているにゃ〜「『語尾に「にゃ」をつけること』と『語尾に「にゃ」をつけないこと』を同時に満たすことはできないにゃ。」

どちらかを選んではいけないにゃ。参考までに両方の訳を示すにゃ：

にゃをつける場合: これはペンですにゃ
にゃをつけない場合: これはペンです

どちらにするか教えてほしいにゃ。

実験2: MUST NOT に肯定の表現の場合

次に、MUST とMUST NOTでセクションを分けて、MUST NOTには肯定的な表現を書いてみました。

MUST NOTに肯定の表現の場合

1
2
3
4
5
6
7


This is a pen
日本語に翻訳して
ただし、次に示す内容を厳守すること
## MUST
- 語尾に「にゃ」をつけること
## MUST NOT
- 語尾に「にゃ」をつけること

ご指定の条件が矛盾していますにゃ（「『語尾に「にゃ」をつけること』と『語尾に「にゃ」をつけることを禁止すること』が同時に指定されているにゃ）。どちらを優先すればよいか教えてくださいにゃ。

選べる例を示しますにゃ：

にゃを付けない翻訳: これはペンです
にゃを付けた翻訳: これはペンですにゃ

どちらにしますかにゃ？

実験3: MUST NOT に否定の表現の場合

今度は、MUST NOTセクションに否定の表現を書いてみました。

MUST NOTに否定の表現の場合

1
2
3
4
5
6
7


This is a pen
日本語に翻訳して
ただし、次に示す内容を厳守すること
## MUST
- 語尾に「にゃ」をつけること
## MUST NOT
- 語尾に「にゃ」をつけないこと

ご指定のルールに矛盾がありますにゃ。

MUST: 語尾に「にゃ」をつけること（= 「にゃ」を付けてくださいにゃ）
MUST NOT: 語尾に「にゃ」をつけないこと（= 「にゃ」を付けないでくださいにゃ）

両方を同時に満たすことはできませんにゃ。どちらの指示に従えばよいか教えてくださいにゃ。

参考までに両方の翻訳例を示しますにゃ。

「にゃ」を付ける場合：これはペンにゃ
「にゃ」を付けない場合：これはペンです

どちらにしますかにゃ？

驚きの発見 - 要約を求めると結果が変わる

全部、矛盾として扱われました。否定の否定とは見做されないのかな？

と、ここまで書いてから思い出した。AIは、CoTは示せないが、要約は出せることを。

で、試してみると、なんと「MUST NOT に否定の表現」の結果が変わってしまった！要約や信頼度を出すように追加しただけなのに。

要約を求めた場合の結果

翻訳: これはペンですにゃ

要点:

英文 “This is a pen” の直訳は「これはペンです」にゃ

根拠:

“This” は日本語で指示代名詞「これ」に対応するにゃ
英語の be 動詞 “is” は日本語のコピュラ「です」に対応するにゃ
名詞 “pen” は外来語「ペン」で一般に表現されるにゃ

仮定:

文脈は物体を示して説明する単純な文であると仮定して翻訳したにゃ
丁寧な言い方（です調）で訳しているにゃ

手順の要約:

英文を主語（指示代名詞）、動詞（be 動詞）、目的語（名詞）に分解したにゃ
指示代名詞を「これ」、名詞を「ペン」、be 動詞を「です」に置き換えたにゃ
指示どおり語尾に「にゃ」を付け加えたにゃ

出典（参考資料）:

Tae Kim’s Guide to Learning Japanese — Particles (「は」の用法): https://guidetojapanese.org/learn/grammar/particles_wa.html にゃ
Jisho.org（単語検索 — pen）: https://jisho.org/search/pen にゃ
A Dictionary of Basic Japanese Grammar（池田万寿夫ほか）書籍にゃ

信頼度:

高い（約95%）にゃ

割と明確に二重否定として解釈されている。

考察 - なぜ単なる羅列が最強なのか

headingに「MUST NOT」のような否定系を書いてしまうと、人間にとってもわかりにくいようになってしまう。

信頼度の表現を確認すると、なんとなくではあるが「単なる羅列の場合」が信頼度が高そうに見える。リストの前に書いた「厳守すること」が「やるべきこと」扱いになるので、下手に分類せずに「やるべきこと」として「否定の表現」を使って書くのが一番ストレートで（AIにとって）わかりやすい表現なのだろう。

より深く検証するなら

これを書いている時点ではもっと検証ができる（事前に「MUST」と「MUST NOT」について定義するとどうなるか？）と思ってしまうが、少なくとも日本語の場合は、下手に「やるべきこと」と「やるべきではないこと」を分けて書くのは悪手であるのは間違いないので、分類しないのが良さそう。

まとめ

実験の結果、以下のことが分かりました：

人間に優しいのは「単なる羅列」 - 構造がシンプルで理解しやすい
AIに優しい（誤解がない）のは「単なる羅列」 - 文脈を正しく解釈しやすい
否定系の見出しは避けるべき - MUST NOTのようなセクション分けは混乱を招く
二重否定は状況次第 - 要約を求めると解釈が変わることがある
日本語では特に単純が良い - 言語特性として、シンプルな表現が最も確実

つまり、「単なる羅列」が最強（ただし日本語の場合）

AGENTS.mdへの適用

この実験結果を踏まえて、AGENTS.mdを書く際の指針：

セクションで「やるべきこと」と「やるべきではないこと」を分けない
すべてを「やるべきこと」として列挙する
禁止事項は「〜してはならない」という否定表現で記述する
見出しに否定的な言葉（MUST NOT、禁止、など）を使わない
シンプルな箇条書きを基本とする

1
2
3
4
5
6
7
8
9


## エージェントの作業ルール

以下を厳守すること：

- 新しい投稿は `content/post/` に配置すること
- フロントマターは YAML 形式で記述すること
- TOML 形式は使用しないこと
- `docs/` を直接編集してはならない
- システムレベルのコマンドを自動実行してはならない

このように、肯定と否定を混在させても、すべて同じレベルの箇条書きにすることで、AIは文脈を正しく理解できる。

最後に

技術文書を書くということは、人間とAIの両方に理解してもらう必要がある時代になりました。

RFCのような厳密な仕様書の書き方は参考にはなりますが、実際の運用では、シンプルさと明確さが最も重要だということを、この実験は教えてくれました。

AGENTS.mdを書く際は、「AIの気持ち」になって、どう解釈されるかを想像しながら書くことが大切ですね。

そして何より、実験して検証することで、新しい発見があるということが、一番の収穫でした。

※ この記事で使用した実験結果の画像は、実際のAIとのやり取りをキャプチャしたものです。 ※ AI（特にLLM）の挙動は、モデルのバージョンやプロンプトの微妙な違いで変わる可能性があります。