tanteki

読者が判断・実装・操作するために必要な情報を、できるだけ短く伝える。短くするために、事実、条件、根拠、例外、誰が責任を持つかを省かない。作業の進め方も、必要な確認ができる範囲で簡単にする。

作業の進め方を選ぶ

ステップ0から順に検討し、依頼に対応できる最も簡単な進め方を選ぶ。ステップ1以上を選ぶ場合は、その理由を作業記録に残す。作業を細かく分けること自体を目的にしない。

ステップ	進め方	この方法では足りない場合
0	自分で構成を確認し、本文を書いて検査する	各節で何を説明するか、構成案を作って検査する必要がある
1	構成案を検査し、別のエージェントに全文の執筆を一度で依頼する	節ごとに資料を分けて読む必要がある、または執筆を分担する
2	構成案の作成と本文の執筆を別々に依頼し、節ごとに分担する	—

指定箇所の修正、短い案内、一つの問いに答えれば済む文書は、ステップ0でよい。ステップ1以上では、執筆の分担と検査に従う。

書く前に決めること

どの進め方でも、本文を書く前に次を決める。決めた内容は、提出する本文の外に一行で添える。

• 文書の種類と読者。文書分類で区分とカテゴリを選び、該当する種類の参照資料を1ファイルだけ読む。その文書が果たす役割と、説明すべき内容を確認する。
• 主題。文書で伝えたいことや、読者ができるようになることを一文で表す。文書の構成に沿い、資料と読者に合わせて説明の順序や節の分け方を決める。
• 出典。各節の根拠となる原資料を示す。
• 用語。言い換えの指定があれば従う。指定がない用語は、最初に出てくる箇所で意味を説明する。
• 図の種類。図を使う節では、図の型を選ぶを参照する。

改稿でも変えないこと

ユーザーが指定した構成・見出し・書式を守る。他の節から参照されている見出し名や識別子も、階層を組み替えても変えない。

原資料の事実・数値・条件・否定・例外を保ち、未決定の事項を確定したように書かない。事実と提案を区別し、資料にない仕様を補わない。

指定箇所の修正では文書全体を組み替えない。既存の正式な参照先で足りる場合は、その参照と補足にとどめる。ただし、ユーザーが明示した作成依頼を省略しない。

名称を一括で置き換えるときは、引用、実際の列見出し、識別子に使われている文字列を対象から外す。原文や実際の名称と一致しなくなる変更を避ける。

合格条件

すべて満たして初めて完了とする。満たせない項目があれば、残る問題を明記して草稿として返す。

• 本文を書く前に構成を検査し、問題がないと確認した。
• 文書の役割を果たす内容があり、情報同士の関係を読者が理解できる。ADR では背景と決定理由、PRD では要求と受入条件、Runbook では操作と停止条件の対応が分かる。
• 表は1セルに1項目とし、全セルを60文字以内に収めた。掲載先の上限がより厳しければ、その上限に従った。並列の項目を読点で詰め込まず、行を分けた。
• 内容の点検と、文章を機械的に検査する textlint の両方を通した。textlint の指摘がなくても、内容の問題が残っていれば合格にしていない。
• 各主張の出典を示せる。原資料にない事実・数値・条件を加えていない。既存文書の表記や目次、語の出現回数だけを、主張が正しい根拠にしていない。
• 合意済みの内容、提案、未決定の事項を区別した。
• 改稿では、情報の重複や節の分け方も確認した。構成に問題があれば、文の言い換えだけで済ませずに直した。

検査して届ける

この SKILL.md があるディレクトリを「スキルルート」と呼ぶ。初回はそのディレクトリで npm ci を実行し、検査に必要なパッケージをインストールする。

検査時は、--type で文書の種類を必ず指定する。次は設計書を検査する例である。種類が異なる複数の文書は、種類ごとに分けて実行する。

node <スキルルート>/scripts/lint.mjs --type design-doc <成果物の絶対パス.md>

検査を通すために、ルール全体を無効にしたり、問題のある文をコードや引用へ移したりしない。パッケージのインストールや検査に失敗した場合は、未検証と伝える。

成果物は本文、またはファイルへのリンクで返す。構成と本文の形式、検査結果は本文の外に一行で添える。構成案、判定記録、モデルの実行記録、検査の詳細は、依頼された文書に混ぜない。執筆の依頼だけを根拠に、送信・公開・Git 操作を行わない。

参照先

知りたいこと	参照先
区分とカテゴリの判定	文書分類
文書の種類ごとの役割と説明すべき内容	種類別の参照先
節の組み方と本文の形	文書の構成
文と語の日本語の判断	日本語の基準
執筆の分担と依頼回数の上限	執筆の分担と検査
検査コマンドと例外の設定	検査コマンドの使い方