xz1220/feishu-doc-style

feishu-doc-style は何をしますか？

飛書ドキュメントを書く際に守るべき規約。技術設計書、PRD、振り返り、説明資料などに適用されます。目標はただ一つ「人に一度読んで理解してもらう」ことです。

使用するタイミング

飛書ドキュメントや技術文書を書く、編集する、レビューする、または推敲する際は、明示的に指示がなくてもデフォルトでこの規約を適用します。

ユーザーが明示的に /feishu-doc-style と入力した場合、または「この書き方で明確ですか？」「どう表現すれば伝わりますか？」と尋ねた場合には、「コア原則」と「提出前の自己チェック」に従って修正を提案します。

他人の原稿を修正する際は、まず自己チェックリストに沿って一つずつ確認し、違反箇所を指摘して修正後の書き方を示し、さらに何を変更したかを説明します。

コア原則

1. 結論だけを残し、推論は書かない。 「なぜこれを選んだのか」「どのように検討したのか」といった導出プロセスは削除し、結論を直接示します。読者が求めるのは答えであって、あなたの思考プロセスではありません。

2. 段落は2〜3行で十分。 1つの段落は2〜3行を超えないようにし、多くの文を1つの大きな段落に詰め込まないでください。長い段落は読むのが疲れます。

3. フローに関する内容は図で表現し、文章では書かない。 誰が先か、データがどのように流れるか、状態がどう変化するかは、図で表現し、長文の説明は避けてください。1つのシーケンス図で多くの文章を代替できます。

4. 矢印は図の中だけに使う。 本文や表の中では「A → B；C → D」のような矢印の速記連鎖を禁止します。これは読者に脳内で逆引きを強要し、翻訳コストを読者に押し付けることになります。

5. 人間の言葉で話し、専門用語は使わない。 内部の専門用語は読者には理解できません。平易な言葉に置き換えるか、初出時に一言で説明してください。よくある専門用語の対照表は references/jargon.md を参照してください。

6. 表のセルは完全な短い文を書く。 セル内に用語の略語を詰め込まず、「誰が何をしたか、結果は何か」を書きます。

7. 装飾用の絵文字やハイライト枠は使わない。 📌 ⭐ 🔒 💡 ✅ 🚧 といった絵文字や、カラーのコールアウトハイライト枠は、ページを乱雑で汚く見せます。強調したい場合は、「太字の小見出し。 本文を続ける」という通常の段落を使用します。ドキュメントレベルの注釈やステータス表示には > 引用ブロックを使用します。全体を通して、装飾用の絵文字やハイライト枠は一切存在してはいけません。

8. 太字は控えめに使う。 セクションごとに多くても1〜2箇所で、本当に全体的な結論や原則の見出しにのみ使用します。名詞リスト、フィールド名、方向を表す言葉（左/中/右）は決して太字にしません。階層は文や表の構造で表現するものであり、画面中に太字を並べるものではありません。

9. キーボードで打てない文字は使わない。 丸数字 ①②③④⑤、ステータスを表す顔文字 ✓ ◐ ◑ ● ○、アイコンとしての !、機能アイコン ⚡ ⌘ — これらは人間が普通に手入力するものではなく、まるで「UIの文言をそのまま書き写した」ように見えます。列挙には通常の「1. 2. 3.」または「第一、第二」を使用し、ステータスは直接「完了/進行中」と書き、ステップ番号は通常の数字（STEP 1）を使用します。

10. 見出しには構造ではなく内容を書く。 見出しにはこのセクションで何を説明するかを直接記述します（「今年の目標と主な手段」「進行中のタスクと進捗」）。組織的な論理や文章作成の枠組みを入れないでください。「総論：」「各論：」「第一部：」のような構造的な接頭辞は書かないでください。総論、各論、並列、順序は、内容の順序と見出しの階層で自然に表現します。また、見出しにメタ説明（「（AIが毎日追加）」のような注釈）は入れず、本文または > 引用ブロックに記載します。さらに、内容を不適切な枠に押し込めないようにしてください。例えば、「方向ごとに進行中のいくつかのタスク」を「上半期の進捗」という時間枠に無理やり入れるのは避けてください。まずこの内容の本当の整理軸（現状は方向で、流水は時間で）を考えてください。自己チェック：見出しを読み上げたとき、人間が普通に付ける名前のように聞こえますか？「総論：今年の目標」は不自然ですが、「今年の目標」は自然です。

表の書き方

列名は人間の言葉で、できれば疑問文形式にします。例：「ユーザーが何をするか / システムが内部で何をするか / オンラインで待つ必要があるか」のように書き、「同期入口 / 非同期経路とDB格納」のような内部用語は使用しません。

セルは完全な短い文であり、一文で誰が何をしたか、結果は何かを説明します。

技術的な詳細は本文に記載し、表はあくまで理解しやすくするために使用します。完全なテーブル作成ステートメントやインターフェース定義などは、本文の専用セクションに記載し、表に詰め込みません。

図表：いつどの図を使うか

図にできるフローは文章で説明しないでください。表現したい内容に応じて図を選びます。

表現したい内容	使用する図
論理フロー、順序、データの流れ方	シーケンス図（mermaid sequenceDiagram）、ロールごとにレーンを分ける
モジュールの階層、依存関係	アーキテクチャ図（カード型ノード：アイコン＋タイトル＋簡単な説明、階層ごとに色分け）
ステータスの遷移（例：下書き→公開→停止）	フローチャートまたは状態遷移図（mermaid flowchart）

これらの図を実際に飛書に取り込む方法（mermaid描画ボード、lark-whiteboard、lark-cliの使い方）については、references/feishu-tooling.md を参照してください。

提出前の自己チェック

提出前にこのリストを一つずつ確認し、1つでも違反があれば修正してください。

• 本文や表に矢印連鎖（A → B）はないか？矢印は図だけに使われているか？
• 各段落は2〜3行を超えていないか？
• 説明されていない専門用語はないか？専門用語の初出には分かりやすい説明が付いているか？
• フローに関する内容は図で表現され、文章で説明されていないか？
• 表のセルは完全な短い文か？列名は人間の言葉か？
• 「なぜこれを選んだのか」という長い推論は削除され、結論だけが残っているか？
• 装飾用の絵文字やカラーハイライト枠（callout）はないか？強調は太字の小見出し、注釈は引用ブロックで行っているか？
• 丸数字 ①②③、ステータス顔文字 ✓ ◐ など、キーボードで打てない文字は使われていないか？
• 太字は控えめに使われているか？各セクションに多くても1〜2箇所の全体的な結論のみで、名詞リストや方位語は太字になっていないか？
• 見出しや表で、主語が裸の英単語になっていないか？デザインモックの英語には中国語の括弧訳が付いているか？
• 見出しは内容を直接命名しており、「総論：／各論：／第一部：」などの構造接頭辞やメタ説明はないか？内容を不適切な時間枠に押し込めていないか？

付属リファレンス

• references/jargon.md：専門用語の対照表。左側の単語はすべて右側の平易な言葉に置き換えます。随時追加されます。
• references/feishu-tooling.md：図を飛書に取り込むためのツールのメモ（mermaid描画ボード、lark-whiteboard、lark-cli）。

このスキル自体もこれらのルールを守る

このスキルの SKILL.md、README、references はすべて上記の規約に従って記述されています。これを編集する際は、まず「提出前の自己チェック」を自分自身に対するチェックとして使用してください。装飾用の絵文字がないか、矢印連鎖がないか、段落は短いか、見出しには内容が書かれているか。ルールが変わったら SKILL.md と README を同時に更新し、両者に矛盾が生じないようにしてください。