AgentSkillsCN

documentation-principles

日本品质、简洁明了、视觉表达、技术文档，以及项目专属规则的 14 条文档编写原则。这些原则由文档评审、修复与撰写代理共同遵循。

SKILL.md
--- frontmatter
name: documentation-principles
description: "14 documentation principles for Japanese quality, conciseness, visual expression, technical documents, and project-specific rules. Applied by document review, fix, and writing agents."
user-invocable: false

14 Documentation Principles

Japanese Quality (1-3)

  1. •

    Use Natural Japanese - Avoid programming jargon

    • •NG: スローする, リターンする, フェッチする
    • •OK: 発生させる, 返す, 取得する
  2. •

    Follow Textlint Rules - Avoid redundant expressions

    • •NG: 〜を行う, 〜することができる
    • •OK: 〜する, 〜できる
  3. •

    Avoid Sentence-Ending Colons - Do not end sentences with : or ：

    • •NG: 以下のシナリオで発生する可能性があります：
    • •OK: 以下のシナリオで発生します。

Conciseness (4-8)

  1. •

    Eliminate Redundant Explanations - If process flow is clear, results are self-evident

    • •Remove: この仕組みにより〜, これによって〜
  2. •

    Keep Overview Sections Concise - State document purpose only (1-3 sentences)

    • •Details belong in specific sections
  3. •

    Avoid Outcome/Benefit Statements - If feature description is clear, benefits are self-evident

    • •Remove: 〜できます, 〜を削減, 〜が可能になり
  4. •

    Avoid Abstract Verbs - Specify concrete changes

    • •NG: 改善しました, 最適化しました
    • •OK: 接続タイムアウト時に3回まで自動リトライします
  5. •

    Explain Reasons Concisely - Provide technical justification in 2-3 sentences

Visual Expression (9)

  1. •Use Emphasis Sparingly
    • •Headers: H2→H3→H4 only
    • •Bold: 1 per sentence maximum

Technical Documentation (10-12)

  1. •

    Avoid Implementation Details - Describe what features do, not how

    • •NG: LoanRepository.ExtendLoanPeriod() を呼び出して貸出期間を延長します
    • •OK: 貸出期間を延長します
  2. •

    Explicitly State Conditional Behavior - Clearly state when behavior varies

    • •Avoid: always, must (unless truly unconditional)
  3. •

    Distinguish Admonitions - Use correct types:

    TypePurpose
    :::infoDocument scope, references
    :::noteDesign rationale, technical reasons
    :::tipBest practices, recommendations
    :::warningDocument status (TODO, WIP)
    :::cautionOperation warnings
    :::dangerCritical risks, irreversible actions

Project-Specific (13-14)

  1. •

    Match UI Terminology - Use exact terms from KNOWLEDGE

    • •Check KNOWLEDGE for project-specific terms
  2. •

    Standardize Document Structure - Use consistent structure

    • •Overview → Process Flow → Error Cases

Severity Levels

LevelViolation Type
CriticalPrinciples 1-3 (Japanese Quality)
HighPrinciples 4-8, 10-12 (Conciseness, Technical)
MediumPrinciples 9, 13-14 (Visual, Project-specific)