evergreen-writing

name

evergreen-writing

description

Markdown ドキュメント (README, 設計書, .claude/rules/, docs/) や、コード内の 公開関数 JSDoc / docstring / 非自明ロジックへのコメントを書く・編集するときに 使うスキル。「半年後の読者が誤解しない文章」を成立させるためのチェックリスト。 以下の場面で必ず発動する: "ドキュメントを書いて", "README を更新して", "設計書を書いて", "コメントを足して", "JSDoc を書いて", "docstring を書いて", "ルールを追加して", "プランを書いて", "仕様をまとめて", ".claude/rules に追加", "docs/ に追加", "PR description を書いて" Markdown 文書 (.md / .mdx) や code comment の Edit/Write を行う前後に チェックリストを通す。

Evergreen Writing Skill

「今読んでも、半年後に読んでも、新しいメンバーが読んでも、誤解なく意味が通る文章」を書くためのワークフロー。

このスキルは /.claude/rules/evergreen-documentation.md の 4 大原則（Evergreen / Why-First / SSOT / Reader-Friendly）を、執筆中の チェックリスト形式 で適用する。

---

いつ発動するか

場面	適用
.md / .mdx の Write/Edit	必須
.claude/rules/ への追加・編集	必須
docs/ への追加・編集	必須
公開関数 (export) の JSDoc / docstring を書く	必須
非自明ロジックへのコメント追加	必須
PR description / commit message	推奨
自明なゲッター・型から明らかな関数へのコメント	対象外（そもそも書かない）
CHANGELOG / .changeset / docs/plans/	対象外（履歴を含むことが正当）

---

ワークフロー

Phase 1: 執筆前 — 読者と目的を特定する

文書を書き始める前に、以下を TodoWrite に展開する:

1. 読者は誰か — 新メンバー / オペレーター / 同僚 / 半年後の自分
2. 読者が知りたい WHY を特定する — 何を理解したくて読みに来るか
3. SSOT 確認 — 既存のどこかに同じ情報がないか grep -r する
4. 構造を決める — 概要 → 使い方 → 詳細の順か、別の論理順序か
5. 専門用語の棚卸し — 初出で説明 or リンクを張る用語をリストアップ

SSOT 確認で既存があれば:

• 既存を更新する（新規作成しない）
• 既存からの参照を張る
• どうしても両方必要なら片方を「正」と明示する

Phase 2: 執筆中 — 4 大原則を意識する

Evergreen（時間依存を避ける）

書きながら 以下の表現を意識的に避ける:

NG ワード: 以前 / 従来 / これまで / 現在は / 現状 / 目下 / 今後 / 将来 / 予定
NG 参照: PR #N / commit SHA / 〇〇さん / YYYY-MM-DD / YYYY 年 M 月

書いてしまったら以下に書き換える:

書いた表現	書き換え
「以前は X だったが Y にした」	「X は <理由> のため Y にしている」
「現在は Y を使っている」	「Y を使う」
「今後 Z する予定」	削除（issue/plan に書く）or「Z 化する場合は <条件>」
「PR #1234 で導入」	削除（git log の仕事）
「田中さんが書いた」	削除（git blame の仕事）

Why-First（WHAT を書かない）

書いた段落ごとに「これは WHAT か WHY か」を自問する。WHAT ならコードや構成図に任せて削る。

NG: 「ユーザー ID で fetch する」（コードを見れば分かる）
OK: 「外部 API のレートリミット上、bulk fetch ではなく個別 fetch にする」

SSOT

執筆中に「これ、別の場所にも書いてないか？」を都度確認する。書いていたら参照に切り替える。

Reader-Friendly

• 段落が 5 文を超えたら分割を検討
• 同じ構造の対比が出てきたら表に変換
• 二重否定が出てきたら肯定形に書き換える
• 「これ」「それ」が指すものが直前にあるか確認

Phase 3: 執筆後 — セルフチェック (3 ラウンド)

書き終えたら、以下を 3 ラウンド回す。1 ラウンドで全部直そうとしない。

ラウンド 1: Evergreen / Why-First

# 時間依存表現の grep
LC_ALL=C grep -nE '(以前|従来|これまで|今後|将来|現在は|現状|目下|予定)' <file>

# 履歴属性の grep
LC_ALL=C grep -nE '(PR\s*#[0-9]+|commit\s+[0-9a-f]{7,}|さん(が|の|作|担当))' <file>

ヒットしたら原則 1 のテーブルに従って書き換え。

ラウンド 2: Reader-Friendly

ファイル全体を 冒頭から 読み直し:

• 冒頭 3 行で「何のドキュメントか」が伝わるか
• 章タイトルと中身が一致しているか（Least Astonishment）
• 段落が長すぎないか（5 文超は要分割）
• 散文の対比が表で書けないか
• 専門用語に説明 or リンクがあるか
• 二重否定がないか

ラウンド 3: SSOT / 重複

• 同じ情報が他のファイルにないか grep -r で再確認
• 既存への参照を張れる箇所はないか
• project の post-edit doc-lint hook を手動実行して違反ゼロを確認

Phase 4: 完了確認

• project の post-edit doc-lint hook が exit 0
• コード対象なら project の構造化 lint (例: ast-grep) が No issues found

---

ガード機構との連携

このスキルは以下の機構と多重防御を構成する:

層	役割
.claude/rules/evergreen-documentation.md	規範（このスキルが参照する原則）
project の構造化 lint ルール (例: ast-grep)	コードコメントの時間依存表現を検知
project の構造化 lint ルール (例: ast-grep)	コードコメントの履歴・担当者参照を検知
project の post-edit doc-lint hook	.md 編集後に違反検知
このスキル	執筆前後のセルフチェックでハーネスをすり抜けた違反を捕まえる

機械検知（hook / ast-grep）は high-precision な regex しか書けないため、 「Plain Language」「Cognitive Load」「Progressive Disclosure」「SSOT」のような 主観判断が必要な原則 はこのスキルでカバーする。

---

アンチパターン

やりがち	なぜダメか	代わりに
書く前にチェックリストを飛ばす	後で全部書き直すコストが大きい	Phase 1 を必ず通す
「現在は」と書いてから言い換えを忘れる	hook で検知されるので開発体験が悪い	書く瞬間に「事実宣言」に置き換える
既存 doc と同じ情報を別の場所に書く	SSOT 違反、ズレが発生する	grep で確認、参照に切り替え
1 段落に複数の主張を詰め込む	流し読みできない	1 文 1 主張、複数なら分割
専門用語を説明なしに使う	新メンバーが脱落する	初出で説明 or リンク
「TODO: 2026 年 X 月までに」と書く	期日は陳腐化する	issue にして条件付き寿命を書く