docs: use GLOSSARY terms verbatim in sessions - #65
Merged
Conversation
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>
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why this change is necessary
AGENTS.md§11 already binds identifiers, comments and commit messages toGLOSSARY.md, but it says nothing about the sentences a development session is actually made of. An agent can name a CSS classcomment-cardcorrectly and, in the same breath, describe it to the user as 「右のパネルのコメント欄」 — and that paraphrase is what lands in the code asrightPanelon 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.mdspells it, so every session decided for itself.Approach
Extend §11 rather than open a new section, so that
AGENTS.mdkeeps exactly one place that sends a reader toGLOSSARY.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:
skills/review-doc/SKILL.md— the rule addresses contributors to reviewer, not people using it.GLOSSARY.mditself is unchanged.Review Points