zhichao1208/better-doc

Better Doc

2つの補完的なフレームワークに基づいて文書をレビューします：

• クラシックスタイル（ピンカー） - 明瞭性、正確性、必要性
• スマートブリビティ（アクシオス） - 構造、スキャン容易性、インパクト

目標：テキストを意味への透明な窓にすること。簡潔さは自信、冗長さは恐れ。

重要なルール：内容を保持する

簡潔さ ≠ 削除。表現を簡素化し、意味を保持する。

既存の文書（特にプロンプト）をレビューする場合：

実行すること	避けること
冗長な要件をより直接的にする	長そうだからといって要件を削除する
回りくどい説明を凝縮する	読み手が必要とするコンテキストを削除する
曖昧な用語を具体的なものに置き換える	制約やエッジケースを削除する
明確さのために再構成する	再構成中に情報を失う

何かを削る前に、自問する：

1. これは要件、制約、またはコンテキストを伝えているか？
2. 削除したら結果が変わるか？
3. 削除する代わりに、同じことをより少ない単語で言い換えられるか？

プロンプトに特化して：

• 段落に埋もれた要件 → 明示的な箇条書きとして抽出
• 暗黙の制約 → 明示的にする。自明だと想定しない
• 冗長なコンテキスト → 凝縮するが、動作に影響する場合は保持する
• 例 → エッジケースを明確にするなら保持、冗長なら削除

間違ったアプローチ：「この段落は長いので削除する。」 正しいアプローチ：「この段落には3つの要件が含まれている。3つの箇条書きに書き換える。」

コア原則

クラシックスタイル（8つの原則）

1. 直接的な言語 - 能動態、明確な行為者
2. 必要な内容のみ - 理解を向上させないものを削除
3. 人工的な複雑さを避ける - 構造は明確さのため、装飾ではない
4. 具体的なものを抽象的なものより優先 - 具体的で検証可能な用語
5. 一貫した用語 - 概念ごとに一つの名前
6. 明確な意図 - 目標、制約、出力形式（プロンプトの場合）
7. 読み手優先の順序 - 順序は理解の経路に従う
8. 検証可能な主張 - 印象ではなく事実と論理

スマートブリビティ（4つの構成要素）

1. 強い見出し - 6単語以内、注意を引く
2. 一つの要点 - 最初の文 = 覚えておくべき唯一のこと
3. なぜ重要か - 読み手にとっての関連性についてのコンテキスト
4. 詳細へ - オプションの詳細、箇条書きに分割

詳細な説明はこちら： references/principles.md

レビューワークフロー

ステップ 1：文書を分類する

タイプ	焦点領域
メール/アップデート	スマートブリビティ構造、スキャン容易性
プロンプト/指示	意図の明確さ、制約、形式
技術文書	正確性、用語、階層
一般的なテキスト	クラシックスタイル、流れ、必要性

ステップ 2：スマートブリビティ構造をチェックする

メール、アップデート、アナウンスの場合：

✓ 見出し：≤6の強い単語か？
✓ 最初の文：一つの重要な要点か？
✓ 「なぜ重要か」：読み手の関連性が明確か？
✓ 詳細：箇条書きでスキャン可能か？
✓ 太字：重要な用語が強調されているか？

ステップ 3：クラシックスタイルをチェックする

原則	赤信号
直接的な言語	受動態、名詞化、埋もれた動詞
必要な内容	フィラー、繰り返し、自明な記述
複雑さを避ける	過剰な書式、入れ子の箇条書き、不要な見出し
具体的に	「様々な」「側面」、未定義の専門用語
一貫した用語	同じものに異なる名前
明確な意図	目標の欠如、曖昧な制約
読み手の順序	トピックの飛躍、結論がコンテキストより前
検証可能	「思われる」、裏付けのない主張

ステップ 4：単語レベルの問題をチェックする

スマートブリビティの単語ルール：

• 短い単語が勝つ：1音節 > 2 > 3
• 削除：副詞、弱い単語、濁し言葉
• 常に能動動詞

削除	保持/置換
「するために」	「～に」
「という事実のために」	「なぜなら」
「現時点で」	「今」
「活用する」	「使う」
「実装する」	「やる」/「作る」
「促進する」	「助ける」/「可能にする」

ステップ 5：結果を報告する

## レビューサマリー

**タイプ**: [メール/プロンプト/技術文書/一般]
**全体的評価**: [一行評価]

## 構造（スマートブリビティ）
- 見出し：[✓/✗ + 修正]
- 最初の文：[✓/✗ + 修正]
- なぜ重要か：[✓/✗ + 修正]
- スキャン容易性：[✓/✗ + 修正]

## スタイル（クラシック）
[場所、問題、修正とともに違反をリスト]

## 改訂案
[要求された場合の改善版]

クイックリファレンス：スマートブリビティ形式

メールやアップデートには、この構造を使用します：

**[6単語の見出し]**

[一文：重要な要点]

**なぜ重要か**: [読み手の関連性について1-2文]

**次にすること** / **詳細へ** / **詳細**:
• [箇条書き1]
• [箇条書き2]
• [箇条書き3]

**結論**: [オプションの締めくくりの要点]

プロンプト固有のチェック

ターゲット構造：

目標：[単一の明確な文]

制約：
- [境界1]
- [してはいけないこと]
- [長さ/形式の制限]

出力形式：[正確な構造]

既存のプロンプトを改善する場合：

元の問題	修正（削除しない）
散文に埋もれた要件	抽出 → 明示的な箇条書き
曖昧な制約（「注意する」）	具体的に（「Xを決して超えない」）
暗黙の前提	明示的に記述
冗長な例	別の例がカバーしている場合のみ削除
エッジケースの長い説明	凝縮し、ルールは保持

最終確定前のチェックリスト：

• 元の要件はすべてまだ存在するか？
• 制約は以前よりも明示的になったか？
• 再構成で失われたものはないか？
• より短く、かつより明確か（単に短いだけではない）？

フラグ：目標の欠如、曖昧な用語（「良い」「適切な」）、出力形式なし。

よくある修正

問題	修正前	修正後
受動態	「データが処理される」	「システムがデータを処理する」
名詞化	「決定を下す」	「決める」
フィラー	「注目すべき重要な点は」	[削除]
長い単語	「活用する」	「使う」
曖昧	「様々な要因」	「コスト、時間、範囲」
弱い見出し	「プロジェクトの状況について」	「プロジェクトは金曜日にリリース」
埋もれたリード	[ポイントの前の段落]	[最初にポイント]

---

関連スキル

信頼性が高く明確なコミュニケーションのためのオープンエージェントスキルの小さなファミリーの一部です：

• reduce-hallucination — LLMエージェントを監査。根拠付け、引用、棄権。
• better-doc — クラシックスタイル＋スマートブリビティ。
• numbers — 数字に意味を持たせ、クリーンに表示。