AIとの会話を技術記事へ変換する手順を調べる

AIとの会話には、技術記事の題材になり得る疑問、失敗、比較、判断が含まれています。

しかし、会話の履歴はそのまま記事の根拠にはなりません。

古い仕様、誤った仮説、再現できない操作、秘密情報が同じログへ混ざるからです。

この前提から、公開までの全自動化は採用しないことにしました。

候補抽出、構成案、一次資料の探索、下書き生成は自動化します。

主張の確認と公開判断は人が行います。

先に公開可能な単位を定義する

会話を記事へ変換する前に、各情報を次の分類へ分けます。

分類	意味	記事での扱い
verified	公式資料やコードで確認できる事実	根拠と確認日を付けて書く
reproduced	自分の環境で再現した結果	環境と手順を限定して書く
reported	会話や他者の報告から得た情報	報告であることを明示する
inferred	複数の事実から導いた推論	推論としてラベルを付ける
opinion	運用上の意見や推奨	適用範囲と条件を書く

この分類を先に置くと、流暢な文章が事実らしく見える問題を抑えやすいです。

仕様、料金、バージョン、対応OS、上限値は一次資料を優先します。

会話内の推測しか根拠がない文は、削るか可能性として書きます。

生ログと公開原稿を分ける

生の会話履歴を公開リポジトリへ置きません。

最初に非公開領域へ保存し、記事候補へ渡すのは必要最小限の要約にします。

除去対象は、APIキー、access token、メールアドレス、顧客名、非公開URL、ローカルパス、未公開コード、個人的な会話です。

秘密情報は伏せ字に置き換えるだけでなく、下書きと中間生成物から削除します。

LLMへ渡す前に、リポジトリのignore設定と入力ファイルの内容を確認します。

生成された文章やリンクも信頼済みデータとして扱わず、公開前に差分を読みます。

会話から候補バックログを作る

1つの会話から1つの記事を機械的に作ると、短く重複した記事が増えます。

候補は次の項目へ正規化します。

仮タイトル
読者が解決できる問題
仮の結論
自分の経験として書ける範囲
外部資料で確認する主張
既存記事との重複
公開優先度
保留理由

複数の会話が同じ問題を扱うなら、共通する調査結果へ統合します。

1つの会話に独立した判断が複数あるなら、記事候補を分割します。

この段階では、文章をきれいにするより公開価値と機密性を判断します。

調査の経路を記事へ残す

記事の下書きには、結論だけでなく調べた順番を残します。

最低限、次の順番で確認します。

会話で何が問題になったかを書く
どの仮説を確認するか決める
公式ドキュメント、ソースコード、リリースノートを読む
自分の環境で再現できる範囲を確認する
事実、報告、推論、意見を分離する
反証や未確認事項を残す

確認できなかったことを、会話の自然な流れだけで補いません。

公式資料が見つからない場合は、記事の結論を狭めるか、未確認としてバックログへ戻します。

Markdownをレビュー可能な成果物にする

AstroのContent Collectionsを使うと、Markdownのfrontmatterをスキーマで検証し、一覧と詳細ページを生成できます。

記事の最小メタデータは、タイトル、説明、公開日、タグとします。

下書き生成では、本文だけでなく次の項目も出力させます。

結論を示す導入
調査の出発点
確認日と前提環境
判断基準
失敗した試行
注意点と未確認事項
参考資料
公開前チェック項目

記事本文と調査メモを混ぜる場合は、読者向けの説明と内部レビュー用の情報を見出しで分けます。

Pull Requestを公開ゲートにする

CIでは、Markdownのlint、リンクチェック、型検査、サイトのbuildを実行します。

GitHub Actionsへ同じ検証を置くと、記事ごとの確認手順を揃えられます。

機械的な検査とは別に、人は次を読みます。

タイトルと結論が一致しているか
事実と経験が混ざっていないか
料金や仕様へ確認日があるか
会話を知らない読者にも前提が伝わるか
既存記事と説明が重複していないか
秘密情報や個人情報が残っていないか
リンク先が主張を実際に支えているか

PRが通ることは、技術的な正しさや公開承認の代わりではありません。

自動公開を止める条件を決める

次のどれかに当たる場合は、公開せず候補バックログへ戻します。

一次資料が見つからない
自分の環境で再現できないのに事実として書いている
既存記事や公式情報と矛盾する
秘密情報が含まれている可能性がある
LLMが追加した主張の出典を確認できない
失敗時に副作用を戻せない手順を自動実行している

停止条件は自動化の速度を下げるが、誤った記事を公開する速度も下げます。

最小構成から始める

大きな収集システムを先に作る必要はありません。

会話を非公開領域へ保存する
定期的に候補をMarkdownのバックログへ追記する
選んだ候補だけ一次資料を調べる
記事を下書きとして生成する
PRで人がレビューする
lintとbuildが成功した後に公開する

この半自動化の目的は、文章の作成者を無人化することではありません。

忘れやすい学びへ根拠を付け、別の読者が検証できる成果物へ変えることです。