開発者のための技術記事を書く

実装や調査の経験を、別の開発者が自分の問題に適用できる記事へ変換する。文章の見栄えより、読者が得る判断材料と技術的な再現可能性を優先する。対象は技術ブログであり、API リファレンスや作業ログの清書ではない。

手順

Step 1: 材料と公開条件を確定する

1. 依頼文、既存メモ、コード、Issue、実験ログから、実際に行ったこと・観察したこと・まだ推測に留まることを分けて抽出する。体験のないテーマであれば、公開資料だけによる調査記事として扱うか、一次経験の提供を依頼する。体験を捏造しない。
2. 公開先、想定読者、記事の長さ、守秘範囲、公開権限を確認する。情報が足りない場合は暫定条件を明記して草稿まで進み、承認が必要な内容は伏せる。
3. 題材の指定がない場合は、最近のバグ調査、設計判断、移行、実験、繰り返し受けた質問、公開可能な学びをメモ・Issue・チームの議論から複数挙げる。継続的な題材探しを求められた場合は、日々の疑問と予想外の結果を候補メモに追記し、開発者コミュニティや同僚の疑問を観察する。非公開の発言は転載しない。
4. 各候補で「直接経験があるか」「読者が避けたい痛み・得たい成果があるか」「説明できる具体的証拠があるか」「公開できるか」を判定して一つ選ぶ。同点なら対象読者と判断をより狭く定義できる候補を選ぶ。固有の具体物（失敗の経緯、設計上の選択、コード、測定結果、予想外の挙動）がなければ調査・実験・取材の必要事項を列挙し、一般論で埋めない。

Step 2: 記事の約束を一文にする

1. 読者を「使っている技術・直面している問題・前提知識」で限定する。
2. 「この記事を読むと、誰が、何を判断または実行できるか」を一文で書く。執筆者の経歴や使った技術名だけを価値提案にしない。
3. 既存記事を軽く調べ、読者がすでに得られる説明と、この経験で初めて付け加えられる知見を分ける。公開先の既存記事も見て、読者の前提、説明の深さ、掲載できる図表・コード形式を確認する。差分がない場合は切り口を狭める。
4. 題材に合う構成を選ぶ。バグ調査・移行・実装過程・教訓・トレンド・製品の技術的背景・測定のいずれかなら、必要な場合にだけスキル同梱の references/article-patterns.md を読む。型が合わなければ読者の疑問順に独自構成を作る。

Step 3: 証拠と構成を先に組む

1. スキル同梱の assets/article-brief.md の「企画・証拠メモ」を埋める。主張ごとに根拠となるログ、コード、設定、実行コマンド、一次資料または実際の経験を対応づける。
2. 時系列をそのまま載せず、読者の疑問から章立てを作る。前提→問題→試みと根拠→結果と限界→適用条件の順を基準とし、型に合わせて変更する。
3. 比較やベンチマークでは環境、入力、対照条件、測定手順、ばらつき、再実行方法を用意する。測定していない性能や改善率は書かない。
4. 重大な根拠が欠ける場合は追加調査を行う。実行できない場合は記事の主張を狭めるか、未検証 として保留する。

Step 4: 作業草稿を書く

1. まず本文の技術的な核を書く。背景説明、導入、タイトルは後から調整してよい。着手できなければ既存メモを貼り、最も具体的な場面から一段落を書く。構成で止まったら Step 3 の見出しだけを書く。技術的な疑問で止まったら [要確認: 何が必要か] と記して該当箇所の調査・実験を先に行い、想像で埋めない。
2. 結論だけでなく「何を見て、なぜその選択をし、他案をなぜ退けたか」を残す。失敗や制約が判断に必要なら省かない。
3. コードは説明に必要な最小部分だけ載せる。実行例なら依存関係・バージョン・入力・期待出力を明示し、可能なら実行する。擬似コードは擬似コードと明記する。非公開コードや秘密情報は掲載しない。
4. 図・表は文章だけで理解しづらい関係や比較を説明する場合に限り追加する。図の意味を本文に書き、画像には適切な代替テキストを用意する。
5. 構成に合わせてスキル同梱の assets/article-brief.md の「記事骨格」を使う。不要な節は削り、空欄を事実らしく埋めない。

Step 5: 読者視点で段階的に推敲する

1. 事実: 各主張が根拠に対応するか、観察と解釈が混ざっていないか、コードや数値を第三者が確かめられるか点検する。
2. 焦点: Step 2 の約束に役立たない背景・宣伝・余談を削る。必要な前提は残す。
3. 流れと明瞭さ: 見出しだけ読んで道筋が追えるか、初出の用語が説明されているか、段落の間に論理の飛躍がないか点検する。曖昧な代名詞・修飾先・長い文を特定し、主語・対象・条件を明示して分ける。文法・表記のゆれを確認し、読者が次に行うことを結びに置く。
4. 読ませ方: 導入と各節の冒頭で具体的な疑問を示し、段落は一つの論点に絞り、必要なら箇条書きや図に移す。実際の失敗・判断・意外な点を自分の言葉で残し、誇張や宣伝調の表現に置き換えない。見出しと最初の一文だけでも要点が追えるか試す。
5. タイトルと冒頭で、対象読者・問題・得られるものを正確に示す。根拠のない煽りや、本文より強い結論を付けない。
6. AI を補助に使う場合は、曖昧な文、論理の飛躍、追加説明が要る箇所の候補を挙げさせる。提案ごとに元の証拠と本文に照らし、誤った指摘を退け、採用した修正は自分の経験・語り口と整合させる。AI に架空の経験・測定・引用を補わせない。

Step 6: レビューを依頼して反映する

1. 技術上の疑問が構成を左右するなら Step 3 の段階で一点に絞って相談する。全体レビューは主張と根拠が揃った草稿で依頼し、公開前に修正と必要な再レビューの時間を残す。重要・論争的な主張や社外関係者を含む場合は早めに関係者を確認する。技術の正確さを見られる人と、想定読者に近い人が確保できるなら別々の観点で読んでもらう。依頼時に読者、記事の約束、固定条件、特に見てほしい疑問を渡す。
2. 指摘を事実誤認・理解困難・好みの差に分ける。事実誤認は修正し、理解困難は本文で解決し、判断を変えない提案は理由を付けて見送る。
3. 人間レビューを実施していない場合は、レビュー済みと書かず 人間レビュー未実施 と明記する。AI の校正結果を実地の技術検証と混同しない。

Step 7: 公開前確認と引き渡し

1. 公開先のプレビューで PC とモバイルの見出し、コードの改行とコピー、表・画像の判読性、リンク先、代替テキストを確認する。プレビューできなければ 表示未確認 と記す。
2. 読者が使う用語から主題を示す語と限定語を選び、本文と一致するタイトル・概要文・URL スラッグ・カテゴリ・タグを公開先で設定できる範囲で提案する。共有時のサムネイルとプレビューの表示を確認する。検索語を不自然に詰め込まない。
3. 記事と一緒に未検証事項・公開承認が要る箇所・更新が必要になりやすい条件を伝える。公開操作は依頼と権限がある場合だけ行う。

Step 8: 公開後に届け、学びを回収する

1. 記事が公開済みで、共有や効果確認が依頼されている場合に限りスキル同梱の references/post-publication.md を読み、読者が実際にいる場と、そこで解決する疑問を対応づける。未公開または草稿のみの依頼なら、公開後の計画を提案するに留めて終了する。
2. 投稿・寄稿・再掲・計測を行う前に、公開権限、媒体のルール、取得可能な指標と観測期間を確認する。外部投稿は明示的な依頼と承認を受けてから実行する。
3. 公開後の質問・誤り・読者のつまずきを記録し、訂正が必要なら記事を更新する。未取得の閲覧数や反応は推定で補わない。

Error Handling

• 根拠が不足する場合: 強い主張を削り、検証可能な範囲の草稿と追加調査項目を渡す。
• 再現用コードが動かない場合: 成功例に書き換えず、失敗した環境・コマンド・出力を残して原因を調べる。
• レビュアーや公開プレビューを利用できない場合: その工程を未実施と明記し、完了扱いにしない。
• 守秘・権利が不明な場合: コード、社内データ、顧客情報、第三者の図版を公開候補から外し、承認を待つ。