はじめに
ども！最近は Claude Code とべったりで、実装 → 検証 → 記事化のサイクルを回している龍ちゃんです。
皆さん、せっかく実装して検証した知見、ちゃんと記事化できてますか？
僕も以前はこんな悩みを抱えていました：
- 実装完了後に「記事書こう」と思っても、何を書けばいいか分からない
- 実装時のメモが散らばって、記事執筆時に情報を集めるのが大変
- 既存記事との整合性を取るのが面倒で、似たような内容を書いてしまう
特に困ったのが、実装から時間が経つと、なぜその設計にしたのか忘れてしまうこと。「あれ、これってどういう意図だったっけ？」とコードを読み返す羽目になり、記事執筆が進まない…。
そこで構築したのが、検証 → 記事化をワンセットにしたワークフローです。この仕組みにより、以下の成果を得られました：
✅ 知見が自然に蓄積（実装と同時にドキュメント化）
✅ 記事執筆時間 50%削減（調査資料が既に揃っている）
✅ 既存記事との整合性確保（RAG もどきで既存記事を参照）
この記事では、実装完了後の知見をブログ記事化する仕組みを、実際のプロジェクト例とツールを交えながら解説していきます。
記事の位置づけ
この記事は、既存の3 フェーズ開発フロー（計画 → 実装 → 検証）を拡張し、検証後の知見を記事化するフェーズに焦点を当てた内容です。
この記事で学べること
この記事を読むことで、以下の知識とスキルが得られます：
🎯 主要なポイント
- フェーズ 3: 研究記録の実践
実装完了後の知見をどう記録するか（/docs/research/） - フェーズ 4: 記事化の実践
調査資料から記事本文への変換方法（/docs/article/） - RAG もどき: ブログ HTML 抽出ツール
既存記事をローカルに保存し、記事執筆時に参照する仕組み - 文体補正システム
writing-style-prompt.md による一貫した記事品質
💡 実践的なテクニック
- research-doc.md（調査資料）の書き方
- no1-article.md（記事本文）への変換パターン
- fetch-blog-html.ts による既存記事参照
- トークン数削減テクニック（50-60%削減）
前提条件
必要な知識
- AI 開発ツールの使用経験
- Claude Code、GitHub Copilot、Cursor 等の AI 開発支援ツールを使った開発経験
- AI にプロンプトを投げてコードを生成した経験
あると理解が深まる知識
- 3 フェーズ開発フローの概念
- 計画 → 実装 → 検証の基本的な流れへの理解
- 以下の記事を参照:
本記事で扱わないこと
❌ 3 フェーズ開発フロー全体の詳細（上記参照記事を参照）
❌ Markdown 記法の基礎
❌ ブログプラットフォーム（Hashnode 等）の使い方
本記事は、フェーズ 3→4（検証 → 記事化）のワークフローに焦点を当てています。
4 フェーズワークフローの復習
まずは、4 フェーズワークフローの全体像を確認しましょう。
4 フェーズの概要
フェーズ 1-2: 計画と実装（概要）
フェーズ 1: 計画（/docs/features/）
- 目的: 実装前の設計・仕様策定
- 成果物: 型定義、API 設計、データベース構造
フェーズ 2: 実装（/application/）
- 目的: 計画に基づいた実装
- 成果物: 動作するコード
詳細は以下の記事を参照してください：
本記事の焦点: フェーズ 3-4
本記事では、実装完了後の知見を記事化するフェーズ 3-4に焦点を当てます。
フェーズ 3: 研究記録（/docs/research/）
- 実装完了後の知見・検証結果をドキュメント化
- 設計思想、アーキテクチャパターン、検証結果を記録
フェーズ 4: 記事化（/docs/article/）
- 技術ブログ執筆に必要な情報収集
- research-doc.md（調査資料）→ no1-article.md（記事本文）の変換
フェーズ 3: 研究記録の実践
研究記録フェーズの目的
実装完了後、「なぜその設計にしたのか」「どんな課題があって、どう解決したのか」を記録するフェーズです。
目的:
- 設計思想と意思決定の記録
- アーキテクチャパターンの検証結果
- 実装完了後の振り返り
記録先: /docs/research/
ディレクトリ構造
研究記録は、単一ファイル形式で管理します（小〜中規模機能に対応）。
docs/research/
├── aoai-chat-simple.md # Azure OpenAI チャット機能
├── github-api-integration.md # GitHub API 統合
└── csv-preview-system.md # CSV プレビュー機能特徴: 1 ファイルで機能検証が完結し、効率的に参照・更新できます。
研究記録に記載する内容
✅ 記載すべき内容
- 設計思想と意思決定（なぜその設計を選択したか）
- 主要エンドポイントの概要（ファイルパス参照）
- 検証結果（パフォーマンス、エッジケース）
❌ 記載しない内容
- ソースコードの全文転記
- 詳細な実装手順
- 機密情報（API キー、認証情報）
実際の研究記録例
このプロジェクトには、20 件の研究記録があります：
単一ファイル形式の例:
aoai-chat-simple.md– Azure OpenAI チャット機能github-api-integration.md– GitHub API 統合csv-preview-system.md– CSV プレビュー機能
ディレクトリ形式の例:
supabase-x-scheduler-v2/– X 投稿スケジューラーの大規模リファクタリングapi-generation-pipeline/– OpenAPI 自動生成パイプラインfrontend-refactoring/– フロントエンド大規模リファクタリング
フェーズ 4: 記事化の実践
記事化フェーズの目的
研究記録をもとに、技術ブログ執筆に必要な情報を収集・整理するフェーズです。
目的:
/docs/features/（計画）+/docs/research/（検証）+/application/（実装）から情報を抽出- 読者向けに再構成
- 記事構成案とコードスニペットを整理
記録先: /docs/article/
ディレクトリ構造
docs/article/
├── CLAUDE.md # 記事執筆ガイドライン
├── writing-style-prompt.md # 文体スタイルガイド
└── {article-topic}/ # ケバブケース命名
├── research-doc.md # 必須 - 調査資料
├── no1-article.md # 必須 - 記事本文
├── no2-article.md # 任意 - 続編がある場合
└── image/ # 必須 - 画像ファイル格納（.gitignore除外）
├── screenshot.png
└── diagram.png重要なルール:
research-doc.mdは必須（リポジトリ内容の調査結果）image/サブディレクトリは必須（.gitignoreで除外済み）- ディレクトリ名はケバブケース（
x-post-with-oauth,azure-functions-local-setup）
research-doc.md（調査資料）の構成
調査資料は、記事執筆の基礎資料となります。主要セクション：
- 記事概要: 対象読者、目的、キーワード
- 参照元ドキュメント: 計画/検証/実装のファイルパス
- 技術スタック: 使用技術とバージョン
- 実装の要点: 主要機能の概要とコードスニペット候補
- 技術的な課題と解決策: 問題、解決策、参考実装
- 記事構成案: H1/H2/H3 レベルの見出し構造
- 図表・資料: 必要な図表のチェックリスト
RAG もどき: ブログ HTML 抽出ツール
RAG もどきとは？
RAG（Retrieval-Augmented Generation）は、ベクトル検索で外部知識を自動取得し、AI が回答を生成する仕組みです。
このプロジェクトでは、既存のブログ記事をローカルに保存し、手動で選択して新規記事執筆時に参照する「RAG もどき」を構築しています。
RAG との違い:
- 本物の RAG: ベクトル化 + セマンティック検索（自動）
- RAG もどき: HTML ファイル保存 + 手動参照
シンプルですが、文体補正や既存記事との整合性確保には十分効果的です。
なぜ RAG もどきが必要か？
記事執筆時にこんな課題がありました：
❌ 既存記事と似た内容を書いてしまう
❌ 既存記事との整合性を取るのが大変
❌ 過去の記事タイトルや文体を忘れてしまう
そこで、fetch-blog-html.ts を使って既存記事をローカルに保存し、記事執筆時に参照できるようにしました。
fetch-blog-html.ts の機能
これは TypeScript である必要は全くありません。好きな言語で実装してください。こちらのファイルの肝となる部分は、ツールとして渡すことでトークン数を削減しながら既存のデータを保存できるという点です。
入力・出力
入力: 環境変数 URL でブログ記事 URL を指定
# /docs ディレクトリで実行
cd /home/node/dev/docs
URL="https://tech-lab.sios.jp/archives/49157" npm run fetch-blog出力: /docs/tools/doc/tech-lab-sios-jp-archives-49157.html
処理概要
既存のブログ記事から HTML を取得し、以下の処理を行います：
- 記事本文のみを抽出（不要なヘッダー、フッター、サイドバーを除去）
- 画像をテキスト化（alt 属性と URL を保持）
- 不要な属性・空白を削除
- トークン数を計算
実装コード: TypeScript実装を公開しています
- fetch-blog-html.ts (GitHub Gist)
- SIOS Tech Lab ブログ用にカスタマイズされています
- 他のブログにも応用可能（セレクタ部分を調整）
実行結果例
実際に記事 49157（Next.js×Nest.js 型定義同期）を抽出した結果がこちらです：
出力ファイル: /docs/tools/doc/tech-lab-sios-jp-archives-49157.html（部分抜粋）
<!--
ブログ記事情報:
タイトル: AIと爆速開発！Next.js×Nest.js型定義同期の自動生成パイプライン構築術 | SIOS Tech. Lab
URL: https://tech-lab.sios.jp/archives/49157
OGP画像: https://tech-lab.sios.jp/wp-content/uploads/2025/09/572995517b0ce827aa745786a62911c5.png
抽出日時: 2025-10-30T01:55:41.785Z
-->
<h1>
AIと爆速開発！Next.js×Nest.js型定義同期の自動生成パイプライン構築術 | SIOS
Tech. Lab
</h1>
<h2>初めに</h2>
<p>
AIと一緒に開発をするようになってから、フロントエンドとバックエンド両方を爆速で開発することができるようになって、検証が爆速で進むようになった龍ちゃんです。
</p>
<p>AIが混乱しないようにプロジェクト自体を整備する方法についてお話しします。</p>
<ul>
<li>
<a href="https://tech-lab.sios.jp/archives/49140"
>Claude Code革命！3フェーズ開発で効率的な開発：計画→実装→検証術</a
>
</li>
<li>
<a href="https://tech-lab.sios.jp/archives/49148"
>AI協働で仕様書アレルギー克服！開発時間を1週間→2日に短縮する実践法</a
>
</li>
</ul>
<!-- 画像はURLのみ保持 -->
<figure>
<img
src="https://i0.wp.com/tech-lab.sios.jp/wp-content/uploads/2025/09/b060e7bc0582b2a27f7c9de8a921557f.png"
/>
(https://i0.wp.com/tech-lab.sios.jp/wp-content/uploads/2025/09/b060e7bc0582b2a27f7c9de8a921557f.png)
</figure>
<!-- ...中略... -->
<h2>まとめ</h2>
<p>
正直、これは導入してみて一番良かったなと思える点ですね。ルールをあまり追加させずにAIに生成させるコードが圧倒的にきれいになりました。
</p>抽出された HTML の特徴:
✅ OGP 情報（タイトル、URL、画像、抽出日時）をコメントで記録
✅ 記事の構造（見出し、段落、リスト）を完全保持
✅ 画像は URL のみ保存（Claude Code で参照可能）
✅ 不要なヘッダー、フッター、サイドバーを除去
✅ 龍ちゃんの文体（「ども！」）も維持
トークン数削減効果
実測値（既存記事 17 件の平均）:
| 指標 | 削減率 |
|---|---|
| 抽出による削減 | 40-50% |
| 圧縮による削減 | 10-15% |
| 総合圧縮率 | 50-60% |
具体例（記事 49157: 型安全パイプライン）:
元ページ全体のトークン数: 35,420
抽出後のトークン数: 18,250（48.5%削減）
最終圧縮後のトークン数: 15,680（14.1%削減）
総削減トークン数: 19,740（55.7%削減）RAG もどきの活用方法
1. 既存記事の一覧確認
ls /home/node/dev/docs/tools/doc/抽出済みの記事を一覧で確認し、類似テーマの記事を探します。
2. 記事執筆時に既存記事を参照
類似テーマの既存記事を選択し、Claude Code に読み込ませます。
# プロンプト例
この記事から発展して、次の記事を考案したいので読み込んでください。
**既存記事**: [抽出済みの HTML ファイル]
**文体ガイド**: /docs/article/writing-style-prompt.md
**記事の位置づけ**: [シリーズ構成、関連記事との関係]既存記事（HTML）+ 文体ガイド（writing-style-prompt.md）+ 記事の位置づけを読み込ませることで、一貫した記事品質とシリーズとしての連続性を維持できます。
RAG もどきのメリット
✅ 既存記事との重複チェック
既存記事を参照することで、似た内容を書くことを防げる
✅ 文体・構成の一貫性
既存記事のスタイルを参考に、統一された記事品質を維持
✅ トークン数削減（50-60%）
記事をローカルに保存し、コード化することでトークン数を大幅削減。Claude Code への入力が効率化される
✅ 不要な記事取得の軽減
記事化している情報をローカルに落とすことで、都度 Web から取得する手間を削減
✅ オフライン参照
インターネット接続なしで既存記事を参照可能
✅ 将来の完全自動化への布石
システムプロンプトを育てることで、検証 → 記事化のナレッジ化まで完全自動化も夢じゃない！
文体補正: writing-style-prompt.md
文体補正システムとは？
writing-style-prompt.mdは、記事を執筆するための文体ガイドです。
仕組み:
- 既存記事から文体を抽出: 投稿済みの記事を分析し、文体パターンをプロンプト化
- プロセス化: 新しい記事を投稿するたびに、文体ガイドをレビュー・更新
- レビュー用システムプロンプトを育てる: 継続的な改善で精度向上
メリット:
- 一貫した記事品質の維持
- AI が文体を学習し、自動的にスタイルに合った記事を生成
- 記事執筆時のレビュー観点が明確化
実践例: 実際の執筆プロセス
本ワークフローの実際の執筆フローを解説します。
ステップ 1: 記事のアイデアをざっくり書く
まず、書きたいことを適当でよいのでざっくり書きます。
- 記事タイトル案
- 伝えたいポイント（箇条書き）
- 想定する読者
- 記事の位置づけ（シリーズ構成等）
この段階では完璧である必要はありません。アイデアをラフに整理するだけです。
ステップ 2: 参照ドキュメントと実装を調査
ざっくり書いた内容をもとに、参照すべきドキュメントや実装を調査します。
調査資料（research-doc.md）に以下を整理：
- 参照元ドキュメント（計画、検証、実装のファイルパス）
- 技術スタック
- 実装の要点（コードスニペット候補）
- 技術的な課題と解決策
ステップ 3: プロンプトとして情報を渡す
記事執筆時にプロンプトとして以下を渡します：
- 参照記事（fetch-blog-html.ts で取得した HTML）
- 記事の位置づけ（シリーズ構成、関連記事との関係）
- writing-style-prompt.md（文体ガイド）
- research-doc.md（調査資料）
Claude Code にこれらを読み込ませ、記事本文（no1-article.md）を執筆します。
ステップ 4: 記事本文執筆とレビュー
Claude Code にプロンプトを渡し、no1-article.md を執筆します。
執筆後のレビュー項目：
- 参照記事との整合性チェック
- 定量的データの妥当性チェック
- 文体チェック（writing-style-prompt.md と照合）
よくある課題と解決法
課題 1: 調査資料が長すぎて AI が混乱
問題: research-doc.md が長すぎると（2000 行以上）、AI が全体を把握しづらくなる。
解決策:
- ディレクトリ形式に分割（research-doc.md, architecture.md, implementation.md）
- セクションごとに記事を分割（no1-article.md: 基礎編、no2-article.md: 応用編）
課題 2: 記事執筆に時間がかかりすぎる
問題: 調査資料から記事本文への変換に時間がかかる（4-5 時間）。
解決策:
- テンプレートを活用（はじめに、Before/After セクション）
- AI に変換を依頼（writing-style-prompt.md + Mermaid 図 + Before/After 比較）
- 段階的に執筆（導入 → 本編 → まとめ）
ワークフロー全体の効果
定量的な効果
| 指標 | Before | After | 改善率 |
|---|---|---|---|
| 記事執筆時間 | 8 時間 | 4 時間 | 50%削減 |
| 調査時間 | 2 時間 | 1 時間 | 50%削減 |
| 既存記事重複チェック | 手動（30 分） | 簡易 RAG（5 分） | 83%削減 |
| 記事品質（一貫性） | 60%（主観） | 90%（主観） | 50%向上 |
※測定条件: 中規模記事（800-1000 行）での実測値
開発者の声（龍ちゃんの実体験）
導入後の変化:
この機能を導入して、ブログを書くっていう行為がまた一つ変わりました。検証した内容からそのままブログ化できるっていうのは本当に便利で、動くコードがそのままブログに転写できるようになったのは大きいですね。
意識的な変化:
ただ、使うにあたって気づいたのが、「明確な意図を持って検証する」必要が出てきたということです。今までは頭の中でやっていた作業を、ちゃんとドキュメント化しなきゃいけない。結構頭を使うようになりました。
Before → After:
- 導入前: 現象を後から眺めて「ブログ書くか」みたいな感じ
- 導入後: 検証の過程を全部ドキュメント化
- 「何を考えてこうやってみたのか」
- 「実際どうなったのか」
- 「最初の予想と結論の違い」
これ全部ドキュメントに残さなきゃいけないので、検証を明確な意識を持って行うようになりました。
全体的な感想:
インプットもアウトプットも、AI が入ってきて変わったなと素直に思ってます。
ワークフロー全体の効果まとめ
✅ 知見が自然に蓄積
実装と同時にドキュメントが作成される
✅ 記事執筆時間 50%削減
調査資料が既に揃っている
✅ 既存記事との整合性確保
簡易 RAG（fetch-blog-html.ts）で既存記事を参照
✅ 記事品質の向上
writing-style-prompt.md で一貫した文体
✅ 記事化のハードルが下がる
「記事書こう」と思った時に、すぐに書き始められる
まとめ
この記事では、検証 → 記事化ワークフローの実践方法を解説しました。
検証 → 記事化ワークフローのポイント
✅ フェーズ 3: 研究記録（/docs/research/）
実装完了後の知見・検証結果をドキュメント化
✅ フェーズ 4: 記事化（/docs/article/）
調査資料（research-doc.md）→ 記事本文（no1-article.md）の変換
✅ RAG もどきシステム: fetch-blog-html.ts
既存記事をローカルに保存し、記事執筆時に参照（トークン数 50-60%削減）
✅ 文体補正: writing-style-prompt.md
一貫した記事品質を維持
効果まとめ
| Before | After |
|---|---|
| 記事執筆時間 8 時間 | 調査資料活用で 4 時間（50%削減） |
| 既存記事重複チェック手動（30 分） | 簡易 RAG で 5 分（83%削減） |
| 記事品質バラバラ | 文体補正で一貫性 90%（主観） |
次のステップ
このワークフローをさらに発展させたい方は、以下の記事もご覧ください：
📚 関連記事シリーズ:
- Claude Code 革命！3 フェーズ開発で効率的な開発：計画 → 実装 → 検証術 ← 本記事の前提知識
- AI 協働で仕様書アレルギー克服！開発時間を 1 週間 →2 日に短縮する実践法 ← 3 フェーズ開発の実践例
- 本記事: 検証 → 記事化ワークフロー（4 フェーズ目の詳細）
🔧 実装詳細・応用編:
- AI と爆速開発！Next.js×Nest.js 型定義同期の自動生成パイプライン構築術 ← API 自動生成の実践
🔜 今後の予定:
- Claude Code× モノレポで実現する AI 協業開発環境（全体像のまとめ記事）
参考リンク
公式ドキュメント
ここまで読んでいただき、ありがとうございました！
検証 → 記事化ワークフローを実践することで、実装完了後の知見が自然に記事化され、技術ブログの執筆が劇的に効率化されます。ぜひ、この記事を参考に、あなたのプロジェクトでも実践してみてください。
質問や感想は、コメント欄でお待ちしております。また、Twitter のほうもよろしくお願いします！
