Design doc writer jp

日本語ソフトウェアデザインドキュメント

意思決定に必要な情報を、読者が短時間で正確に理解できる日本語のデザインドキュメントにする。 文体の美しさより、設計判断の明確さ、章間の論理、用語の一貫性、検証可能性を優先する。

必須規則

1. ユーザーが別言語を指定しない限り、日本語で書く。
2. 新規文書では基本章構成から始める。
3. 章を追加するときは、前提章の後かつ利用章の前に置く。
4. 一文には、独立して評価できる主要な主張を一つだけ含める。
5. 複数の独立項目を並列に説明するときは、箇条書きまたは表を使う。
6. 一つの概念には一つの標準用語を割り当て、表記揺れを残さない。
7. 新たに作成する図は、すべてMermaidのコードブロックで記述する。
8. 事実、決定、前提、仮定、未決事項を混同しない。
9. 不明な数値、名称、日付、担当者、既存仕様を創作しない。
10. 設計の主張には、理由、制約、影響、または検証方法のうち必要な情報を添える。

開始時に読む資料

依頼種別に応じて、次だけを読む。深掘りは参照表から必要なファイルだけ追加する。

依頼	読む参照
新規作成	章構成、日本語表現、文章・表・図、テンプレート
改訂・構成整理	章構成、日本語表現、文章・表・図
レビュー	章構成、日本語表現、文章・表・図、レビューガイド
表現のみの軽微改訂	日本語表現。必要なら文章・表・図

文書全体の完成度の目安は、見本を参照する。

知識グラフ向けの依存ディレクティブが必要な場合は、このスキルの範囲外とする。別途 writing-markdown-document などを使う。

執筆ワークフロー

1. 依頼と読者を特定する — 決めること、読者、範囲、制約、根拠を抽出する。結果を左右する不足だけ質問し、それ以外は前提または未決事項にする。
2. 主張と依存関係を整理する — 文書が答える問いを列挙し、章構成の依存関係で並べる。
3. 用語表を作る — 本文より先に標準用語を登録する。
4. 章ごとに下書きする — 主張 → 根拠 → 仕組み → 影響/検証の順。正常系のあと異常系。
5. 表現形式を選ぶ — 文章・表・図に従う。
6. 推敲する — 章順、主張と検証の対応、事実と仮定、一文一義、用語、Mermaid、未決事項。

作業種別

種別	扱い
新規作成	テンプレートから始める。該当しない重要章は削除せず、該当しない理由を一文で書く。
改訂	既存の事実・決定・外部参照を維持し、構造と表現を改善する。意味が変わる修正は言い換え扱いにしない。
レビュー	レビューガイドに従い、意思決定を妨げる問題から指摘する。依頼されていない全面書き換えはしない。

完了条件

• 読者が、解決する問題と採用する設計を要約できる。
• 目標、要件、設計、検証方法の対応を追跡できる。
• 代替案を退けた理由と主要なトレードオフが分かる。
• 運用、移行、失敗時の扱いが判断できる。
• 未決事項に、影響と解決条件が記載されている。
• 文書内の図がすべてMermaidで記述されている。
• 同じ概念が同じ用語で表記されている。

参照一覧

参照	用途
document-structure.md	基本章、依存関係、追跡ID
japanese-style-guide.md	文体、一文一義、規範、曖昧語、用語
representation-guide.md	文章・表・図・Mermaid
design-doc-template.md	新規作成テンプレート
review-guide.md	レビュー手順と指摘形式
examples.md	文書レベル見本への入口
example-image-cdn-cache.md	見本: 画像配信のキャッシュ方式
example-agent-log-aggregation.md	見本: AI Agentログの中央集約方式