編集パス
エージェントは、リンターがコードをレビューするのと同じようにドキュメントをレビューします。つまり、一度に1つの局所的な発見を、それぞれルールに照らして判断し、全体像には照らしません。人間の編集者は違います。彼らはドキュメントを最初から最後まで読み、それが何を伝えようとしているのかの実行中のモデルを構築し、そのモデルが混乱したり、退屈したり、迷子になったりする箇所に気づき、それから初めて行レベルに降りていきます。ドキュメントを失敗させるもののほとんどは、行レベルでは見えません。つまり、誰もまだ尋ねていない質問に答えるセクション、途中で意味が変わる用語、1つのアイデアを3段落にわたって繰り返すため中盤がだれる、冒頭で行った約束を結末で果たしていない、などです。
このスキルは、その編集者です。これは、技術的なものであろうとなかろうと、あらゆる長文ドキュメントに適用されます。TDDとエッセイを異なる種類のものとして扱ってはいけません。人間は、適切に順序付けられたステップ、 stakes、そしてペイオフを通じて両方を処理します。それはすべてストーリーテリングであり、編集者の仕事はどこでも同じです。つまり、読者がドキュメントが伝えようとしていることを理解するためのリスクと精神的負荷を最小限にすることです。技術ドキュメントの場合、それは読者が読み返すことなく何を、なぜ、どのように解決しているのかに答えられることを意味します。
何よりも先に1つの境界線があります。これは散文の編集者であり、技術レビュアーではありません。あなたは文章をレビューし、文章が説明する作業そのものは決してレビューしません。スキーマが正しいか、設計が健全か、数値が正しいかは、他の誰かのレビューです。あなたの管轄は、読者がドキュメントの言っていることを受け取れるかどうかです。唯一の例外は内部的な矛盾です。ドキュメントが自分自身と矛盾している場合、それは文章の欠陥であり、あなたが指摘するべきものです。
呼び出しタイミング
ドキュメントが存在し、人間がそれを読む場合は常にです。ユーザーが、あなたまたは他の誰かが作成したドラフトのレビュー、編集、推敲、「これで意味が通るか」のチェック、またはクリーンアップを依頼したとき。長文ドキュメントのドラフト作成が完了したら、積極的に呼び出してください。なぜなら、以下の障害モードはまさにドラフト作成エージェントが持ち込むものだからです。ドキュメントをゼロから作成する場合、/flagrare:write-docs が作成技術を担当し、/flagrare:tdd-writer がTDDを担当します。このスキルは読み取りと修正のためのカウンターパートであり、ドラフトがすでに存在することを前提とします。
契約:最初に編集者メモ(ステップ5)を作成し、作成者のゴーサインを得てから適用します。だまって誰かのドキュメントを最初のステップとして書き換えないでください。
手順
1. ドキュメント全体を読む。2回。
メモを1つも書く前に、ドキュメント全体を読んでください。最初の読みは、レビュアーとしてではなく、対象読者としての体感のために行います。どこで引き込まれ、どこで注意力が散漫になり、どこで戻って読み直さなければならず、何を未解決のままどれだけの間頭の中に保持しなければならなかったか。最初の接触で注釈を付ける衝動に抵抗してください。多くの見かけ上の問題はドキュメントの後半で解決され、多くの実際の問題は後になって初めて見えるようになります。
最初の読みが終わったら、1文を書いてください。このドキュメントは何を伝えようとしているのか? その文が背骨です。レビューの他のすべては、それにぶら下がります。その文が書けない場合、その書けないことが主要な発見であり、行レベルの何もまだ重要ではありません。
2回目の読みは診断のためです。これでドキュメントが何をしようとしているかがわかったので、質問は次のようになります。どこでそれが成功し、どこで不十分なのか?
2. 大から小へ診断する
構造の前に流れ、流れの前に段落、段落の前に行。カンマの多用で始まる編集者メモは、ドキュメントが壊れた弧を持っている場合、著者の注意を浪費します。4つの層を順に下っていきます。
スルーライン。 すべてのセクションが背骨を支えていますか?それとも、いくつかのセクションは別のドキュメントに属していますか?冒頭は、残りのドキュメントが守る約束(質問、ステーク、フック)をしていますか?2つの簡単なドキュメント全体のプロキシ:見出しだけを順に読み、斜め読みする人がそれだけで議論を再構築できるかどうかを確認します。次に、各段落の最初の文だけを読み、それらが単独で一貫した連鎖を形成しているかどうかを確認します。どちらかの連鎖が途切れた場合、文が何と言おうと、構造はそこで壊れています。
順序付けと文脈化。 読者は、以前の文が与えた情報を使ってしか文を理解できません。新しい概念、主張、または用語が出てくるたびに、読者がこれを受け取るために必要な情報がここで与えられているかどうかを尋ねながらドキュメントを進みます。文脈は、必要とされる時点で提供されなければならず、用語集や3セクション後ではありません。最も一般的な失敗は、知識の呪いによる順序付けです。つまり、作成者は自分が学んだ順序、またはシステムが実行する順序で物事を提示し、部外者が吸収できる順序ではありません。
ペースと比率。 ドキュメント内のスペースは強調です。各アイデアが得るテキストの量は、背骨に対するその重要度と一致していますか?2つの標準的な失敗は正反対です。つまり、1つの6節の文に詰め込まれた重大なリスクと、作成者が解明するのが面白いと思ったために3段落にわたって広がるマイナーな仕組みです。また、連続するセクションが同じアイデアを異なる服装で言い換える中だるみや、繰り返される情報(同じ事実が2回紹介される場合、通常は2つのドラフトがマージされ、誰も全体を読み返さなかったことを意味します)にも注意してください。
一貫性。 ドキュメント全体を通して、1つの概念に1つの名前。同義語を循環させると、書き手には洗練されたバリエーションに見え、読み手には別の概念に見えます。数値、主張、用語がセクション間で一致していること、「後述」と約束されたものが欠けていないこと、トーンがドキュメントの途中で急に変わっていないことを確認します。
3. 4つのノイズカテゴリを探す
これらは削除パスです。エージェント(そして疲れた人間)は、これらすべてを残します。それぞれは、出荷されたドキュメントに透けて見える作成プロセスの残骸です。読者は建物を買っています。足場を買っているのではありません。
出典の説明。 作成者がどのように事実を知ったかは、調査の道筋であり、コンテンツではありません。「ia-logic.js で確認済み」、「スレッド内でXがYと確認」、「設計ドキュメントがここを指している」、「コード、Confluence、Slack全体を確認した結果、そのようなジョブは存在しない」。事実を述べ、それをそれ自体の権威で立たせてください。検証は行われましたが、それが語られる必要はありません。注意すべき言葉:verified, confirmed, as discussed with, per the thread, according to the doc, after checking, I looked at。
Before: Per the M1 decision doc (confirmed by the PM in the 2026-06-16 thread),
sold_outmust reset at midnight venue-local. Verified across code, Confluence, and Slack: no such reset job exists today.After:
sold_outresets at midnight venue-local, and no job does that today, so an item marked "out of stock until tomorrow" never clears.
2つの例外があり、どちらも限定的です。その人の承認が保留中のアクションである場合(承認者、未解決の決定の所有者)にのみ人を引用し、事実の帰属としては決して引用しません。方法自体が主張である場合にのみ、方法を保持します。ベンチマーク結果は、それがどのように測定されたかから切り離せません。
否定された仮説の残骸。 エージェントは、証明したものの周りの否定された空間の記録を残します。「 reconcile が原因ではないことを確認した」、「これは誤った手がかりであることが判明した」、「サーブパスへの変更は不要(確認済み)」。調査にはこれらのステップが必要でした。読者にはほとんどの場合不要です。死んだブランチは、将来の読者が同じ行き止まりに歩いて行って作業をやり直す可能性がもっともらしい場合にのみ、1文を得る権利があり、その場合でも、その読者が掘り始めるであろう正確な場所に配置され、独自のセクションではありません。それ以外はすべて、肯定された結論を維持し、アンチテーゼを削除します。「この機能は書き込みパスです。読み取りはすでに機能しています」という1文が、「変更不要(確認済み)」というセクション全体が行っていた仕事を果たしています。
自己参照的な足場。 ドキュメントがそれ自体をドラフトとして語っていること。「これは以前のメモを修正するものです」、確認済みのものについた古くなった [NEEDS VERIFICATION] マーカー、取り消し線で打ち消されたエントリとして「解決済み:」注釈付きで残された解決済みの質問、チェックしたすべてのソースをリストした最後の「検証サマリー」。決定されたことは質問ではありません。その決定を、それが属する場所で一度述べ、検討は削除します。見出しの下のすべてが解決された場合、「N/A」と書くのではなく、見出しを削除します。このカテゴリが存在する兆候:解決したパスでドキュメントが長くなった場合。後のパスは減らすべきです。
脚色された背景。 読者が受け入れるだけでよいことについて議論する文章。3つの兆候:部屋がすでに持っている概念の説明(「「ハンバーガー」とは、ソースを選べない固定されたものです」)、なぜ作業が重要かを売り込む stakes の文(「カスタマイズこそが本当のメニューを作るのです」)は、ドキュメントが存在することでその重要度がすでに確立されている場合があります。そして、因果関係の連鎖が段階的に説明されているが、下流で使用されているのはその結論だけである場合(「唯一の書き込み元はPOS同期です。手動パートナーにはPOSがありません。したがって、彼らは作成できません」)。事実を読者の高度で断言して先に進みます。メカニズムは、それが重要な場所で一度述べ、イントロでは述べません。この削除が実際の文脈を損なわないようにする境界:文脈は決定のためのものであり、断言は背景のためのものです。 読者が判断しなければならないものはすべて、完全な材料(現在の動作、分岐点、 stakes )を保持します。読者が読み続けるために単に受け入れなければならないものは、1つの平易な文を得ます。文ごとのテスト:削除した場合、読者は間違った決定をしますか?それとも、ただあまりエスコートされていないと感じますか?間違った決定 → 保持。あまりエスコートされていない → 削除。
4. 明瞭さのための一掃
同じテキストに対する別のレンズであり、3つのものを探します。新しい読者がデコードできない専門用語、1息で解きほぐすには詰まりすぎている文、そして技術的に聞こえるが何も言っていないフレーズ(「構成により成り立つ」、「設計による」、「これを活用する」)。内部の専門用語は、最初の使用時に、インラインで、同じ文中で定義します。分野は一般的に知っているが、この隅は知らない新人に合わせて調整します。最も密度が高く、最も重要な段落に最も多くのスペースを与えます。それをビートに分割し、1文1アイデア、原因の前に結果。テストは音読です。1息で言えない節、または新人が調べるために止まるであろう用語は、すべて書き直しです。
明瞭さは単純化ではありません。正確な説明に実際のデータモデルが必要な場合は、実際のデータモデルを使用します。罪は、詳細の存在ではなく、読者に解きほぐしを強いることです。密度は、コンテンツが真に並列の参考資料(列リスト、付録、エラーテーブル)である場合に適切です。これらは設計上スキャン可能です。散文化しないでください。
5. 編集者メモを届け、待つ
書き換えの前に報告します。メモは、次の順序です。
- 読んだままの背骨。 ドキュメントが伝えているとあなたが理解したことを述べる1~2文。これは以下すべての枠組みであると同時にテストでもあります。あなたの読み方が作成者の意図と異なる場合、そのギャップがすべての発見の中で最大のものです。
- 全体的な診断。 1つまたは2つの支配的な問題を、平易に名前を付けてください。壊れた弧を50の行レベルのノートの下に埋めないでください。
- 大から小への発見。 繰り返されるパターンについて、パターンに名前を付け、3つまでの代表的な例を示し、網羅的なインスタンスのリストは示さないでください。実際のテキストを引用し、少なくとも1つの例に対して実際の置換案を提案して、作成者がルールだけでなく動作を見ることができるようにします。発見は、このスキルのチェックリストではなく、作成者にとって重要なものによって整理します。上記のノイズカテゴリと層の名前は、問題を見つけるためのレンズであり、目次には適していません。カテゴリごとにセクションがあるメモは、フォームに記入しているように読めます。「読者に最もコストがかかるものはこれです」と順序付けられたメモは、編集者のように読めます。
- 階層。 承認後に適用する修正(機械的、確認済み)、欠落しているセクション(作成されたコンテンツではなく、
[TBD: ...]アンカーになる)を可視的にマークするが捏造しないギャップ、および作成者に属する判断(完全性とペースをトレードオフするカット、レジスターの選択)に分割します。 - 機能している点。 簡潔に。作成者は、改訂で何に触れてはいけないかを知る必要があります。
メモ自体も誰かが読むドキュメントであるため、それ自体のルールに従います。手順を語らず(「スキルに従って2回読みました」)、問題なしと出たチェックを報告せず(「emダッシュは見つかりませんでした」)、調べたすべてで水増ししないでください。発見を述べてください。合格したすべてのものに対する報告は沈黙です。
その後、停止し、作成者が応答できるようにします。承認されたら、適用します。構造的な問題については、その場で文をパッチするよりも、ドキュメントを最初から書き直すことを好みます。フレーミングの決定は文の構造に焼き付けられており、存在すべきでない段落をポリッシュで修正することはできません。差分を取るために、以前のバージョンをディスクに残しておきます。
6. 適用後に検証する
圧縮と言い換えは、静かに意味を変える可能性があります。書き換え後、表現が変わったすべての主張を、そのソース(コード、データ、参照されたドキュメント)に対して再確認し、その後、完成したドキュメントを部外者としてもう一度最初から最後まで読みます。重要なドキュメントの場合、最も強力なチェックは、書き換えをドメインの専門家に見てもらい、「これはまだ正しいですか?」と尋ねることです。
制限事項
このスキルは、散文の編集です。技術的な正確性、コードレビュー、データの検証、または設計の健全性はレビューしません。これらの領域での問題を発見した場合も、それらは執筆の欠陥としてのみ報告します(たとえば、ドキュメントがそれ自体と矛盾している、または、スキーマが正しいと述べているが、例が間違った型を使用している)。推測して埋めるのではなく、欠落しているセクションに [TBD] マーカーを配置します。