Skip to content

docs: use GLOSSARY terms verbatim in sessions - #65

Merged
handlename merged 1 commit into
mainfrom
docs/raw-glossary
Aug 29, 2026
Merged

docs: use GLOSSARY terms verbatim in sessions#65
handlename merged 1 commit into
mainfrom
docs/raw-glossary

Conversation

@handlename

Copy link
Copy Markdown
Owner

Why this change is necessary

AGENTS.md §11 already binds identifiers, comments and commit messages to GLOSSARY.md, but it says nothing about the sentences a development session is actually made of. An agent can name a CSS class comment-card correctly and, in the same breath, describe it to the user as 「右のパネルのコメント欄」 — and that paraphrase is what lands in the code as rightPanel on the next round. Conversation is where identifiers come from, so it was the one place the vocabulary rule did not reach.

The gap is sharpest when the session is not conducted in English. Nothing in the repository said whether a term should be translated, transliterated, or kept exactly as GLOSSARY.md spells it, so every session decided for itself.

Approach

Extend §11 rather than open a new section, so that AGENTS.md keeps exactly one place that sends a reader to GLOSSARY.md. The rule states that a term is a name and a name is not translated: the sentence around it takes the session's language, the term does not. It names the surfaces it covers — chat, scratch notes, plans, PR and issue bodies, review_reply — so the boundary matches the one §11 already draws for commit messages, and it notes that the wire-format exception below it travels with the rule.

A Bad/Good pair set in a Japanese session shows the intended shape, since that is the case the rule exists for. The example stays in Japanese deliberately: translating it into English would leave nothing to illustrate. That is the one considered deviation from §1.

Scope

Deliberately out of scope:

  • Mechanical enforcement (hooks, lint, CI) — this is documentation only.
  • skills/review-doc/SKILL.md — the rule addresses contributors to reviewer, not people using it.
  • How the agent should react when the user uses a different word; only what the agent writes is governed.
  • What to call a concept that has no glossary term yet mid-conversation. §11's existing "a thing with no term yet needs a term first" continues to cover code.
  • GLOSSARY.md itself is unchanged.

Review Points

  • Whether §11 is the right home, or whether this belongs next to §1 as a language policy.
  • Whether a Japanese Bad/Good example is acceptable inside an English document, given §1.
  • Whether the listed surfaces — PR and issue bodies in particular — draw the boundary in the right place.

AGENTS.md §11 bound identifiers, comments and commit messages to
GLOSSARY.md, but said nothing about the sentences a session is made of.
A term paraphrased in conversation — translated, transliterated, or
replaced by where the thing sits on the screen — is the term that lands
in the code as `rightPanel` on the next round. Conversation is where the
identifiers come from, so it belongs under the same rule.

The addition covers what the agent says in chat and what it writes
during a session: scratch notes, plans, PR and issue bodies, and
`review_reply`. The wire-format exception travels with it. A Bad/Good
pair shows the intended shape in a Japanese session, which is the case
the rule exists for; the example stays in Japanese because translating
it would leave nothing to illustrate.

User request: 開発中のセッション内で用いる用語について、GLOSSARY.md に
あるものをそのまま利用するようにしたい。ユーザーとのやり取りに英語以外の
言語を使用している場合も、用語についてはその言語に訳す必要はない。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@handlename
handlename merged commit 4620cdc into main Aug 29, 2026
2 checks passed
@handlename
handlename deleted the docs/raw-glossary branch August 29, 2026 11:04
@handlename handlename mentioned this pull request Aug 29, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant