chore: Add document and prompt rules and expand comment rule for third-party readers

Author: hanatyan128

.claude/rules/comment.md

@@ -5,5 +5,8 @@ When writing or modifying code, follow these rules for comments.
 - **Fix the code, don't write an essay justifying it.** Multi-paragraph comments defending "why this is safe enough" hurt readability and invite re-litigation in later reviews.
 - **Defer with a FIXME, not a rationale.** When the root-cause fix is out of scope (needs its own PR, design decision pending, intentional deferral), leave a short `FIXME:` / `TODO:` — one or two lines stating the problem and the recommended fix direction — instead of an exhaustive explanation.
 - **Longer comments are for genuinely non-obvious invariants.** Only when the invariant cannot be inferred from the code itself. Even then, keep it to one tight paragraph.
+- **Comments are written for third-party readers who will read the code later, not for the user you're chatting with.** Avoid subjective writing that depends on the chat context. A third-party reader doesn't know "what the user asked for", "what the prior code looked like", or "which file the logic was ported from".
+  - NG example: After refactoring logic from `a` into `b`, writing `// Original logic from a, modified in b as ...`. The third-party reader has no knowledge of `a` or of the porting history — chat-context-dependent wording doesn't work for them.
+  - Instead: If a comment is needed, document only the invariants, constraints, or assumptions that cannot be read from the code itself, in a form that stands alone within the codebase. Leave change history in git log / PR descriptions; do not put it in comments.
 
 These rules apply to code comments, not to user-facing documentation (API references, README, etc.), which have their own audience and constraints.

.claude/rules/document.md

@@ -0,0 +1,30 @@
+# Documentation Discipline
+
+When writing or modifying documentation, follow these rules.
+
+These rules do not apply to AI-facing prompts (agent definitions, skills, commands, rules, etc. under `.claude/`).
+
+## Audience awareness
+
+- **Documentation is written for third-party readers who consult it later, not for the user you're chatting with.** Avoid subjective writing that depends on the chat context. A third-party reader doesn't know "what the user asked for", "what the prior version of the doc said", or "which file something was ported from".
+  - NG examples: Phrasings that presume the chat context, such as "Added per user request" or "Previously was X, now changed to Y".
+  - Instead: Document only the facts, specifications, and assumptions readable from the doc itself, in a form independent of any conversation history. Leave change history in git log / PR descriptions; do not put it in the doc body.
+- **Exception**: This does not apply when the user explicitly asks for such phrasing, or when the doc is itself an extension of the chat context (plans, reports, meeting notes, etc.).
+
+## Reference independence
+
+- **Do not reference matters that have not been documented in a form a third party can access.** Verbal decisions, Slack messages, chat history, unpublished material, etc. must not be cited as sources.
+  - When citing, point to a place a third party can follow (a file in the repo, a public URL, a published spec, etc.).
+  - When no such public reference exists, do not include the citation at all — rewrite the passage so the doc stands on its own.
+
+## Markdown notation
+
+- **Escape `|` inside inline code in table cells.** Markdown's table cell separator is `|` even inside inline code, so leaving it unescaped breaks parsing. Escape it as `\|`.
+  - NG: `| operator | `a | b` represents OR |`
+  - OK: `| operator | `a \| b` represents OR |`
+- **Wrap Markdown source at a reasonable width (target: 100 characters max).** Don't pack a long paragraph onto one line; break at sentence or clause boundaries to preserve readability and diff clarity.
+  - Exception: Places where Markdown forbids line breaks (table rows, heading lines, etc.).
+- **A single newline in Markdown source does not produce a line break in the rendered output.** The viewer treats source newlines as whitespace and joins them into one paragraph. To split lines visually, use one of:
+  - Separate paragraphs: insert a blank line.
+  - Separate items: use a list (`-` or `1.`).
+  - In-paragraph line break (use sparingly): two trailing spaces at end of line, or a `<br>` tag.

.claude/rules/prompt.md

@@ -0,0 +1,37 @@
+# Prompt Discipline
+
+When writing or modifying AI-facing prompts (agent definitions, skills, commands, rules, etc.), follow these rules.
+
+These rules do not apply to human-facing documentation (README, API references, design docs, etc.). Human-facing documentation is governed by [document.md](document.md).
+
+## The reader is an AI
+
+- The reader of a prompt is an AI agent. Explanatory writing aimed at users or other humans is unnecessary.
+- Do not write meta-commentary like "This prompt was created to ..." or "The following describes ...". Write the instruction itself.
+- Limit explanations of background and motivation to what the AI needs for judgment. Do not include history that does not affect the AI's work.
+
+## Structure and decoration
+
+- Excessive decoration is unnecessary. Keep heading hierarchy minimal.
+- Use the minimum line breaks required. Separating paragraphs with blank lines is enough.
+- As a rule, do not use tables. Replace them with bullet lists.
+  - Exception: When specifying an output format for the AI, showing a table as an output example is acceptable.
+- Use emphasis (`**` and `*`) only for genuinely important points. Overuse dilutes the meaning.
+
+## Eliminating context dependence
+
+- Do not write in a way that depends on the chat context (same policy as [document.md](document.md)).
+- Avoid phrasings that presume conversation history, such as "Because the user said ..." or "In the previous prompt ...". Each prompt must stand alone.
+
+## What to include
+
+- Include only the instructions and context the agent needs to do its work.
+- Drop digressions, supplementary remarks, and "just-in-case" information. AI accuracy degrades with verbose instructions.
+- Write instructions concretely. Avoid vague directives ("appropriately", "nicely", etc.); state the judgment criteria explicitly.
+
+## Output format instructions
+
+- When the AI outputs Markdown, note that Markdown viewers do not render single newlines as line breaks.
+  - To split lines visually, use a list (`-` or `1.`) or separate paragraphs with a blank line.
+  - Just inserting `\n` results in a single paragraph with whitespace separating the parts after rendering.
+- When instructing the AI to produce Markdown output, write the format spec with this in mind.