Technical Writing Review Workflow with AI Agent

AIエージェント（Cline）を活用した、テクニカルライティングの体系的なレビューワークフロー

🎯 概要

このワークフローは、エンジニア・非エンジニアを問わず、 テクニカルドキュメントを作成するすべての人を対象としています。

定義されたガイドラインに基づき、ドキュメントを項目ごとに段階的にレビューします。 AIエージェント（Cline）が各項目を1つずつ確認し、指摘と修正方針案を提示します。 ユーザーの確認を経て、修正版を作成するところまでをサポートします。

✨ 特徴

• 段階的レビュー: ガイドラインの項目を1つずつレビュー（トークン制限対策）
• 中断・再開可能: レビュー進捗を保存し、いつでも続きから再開
• 完全なトレーサビリティ: 指摘、修正方針案、修正版をすべて記録
• カスタマイズ可能: 独自のガイドラインを使用可能

📋 必要な環境

• VS Code: コードエディタ
• Cline: VS Code拡張機能のAIエージェント
• Git: バージョン管理（オプション）

🚀 セットアップガイド

1. リポジトリのクローン

git clone https://github.com/yoshitak1212-dev/technical-writing-review-workflow
cd technical-writing-review-workflow

または、GitHubの「Use this template」ボタンで自分のリポジトリを作成。

2. ガイドラインの準備

オプションA: サンプルガイドラインを使用

• guidelines/sample-guideline.mdをそのまま使用

オプションB: オリジナルガイドラインを使用

• guidelines/sample-guideline.mdを自分のガイドラインに置き換える
• またはguidelines/active-guideline.mdとして保存

ガイドラインは以下の表形式で記述：

| 項目番号 | レビュー観点 | 観点説明 |
|---------|------------|---------|
| 1 | 目的・対象読者の明確さ | この文書が「誰に向けて」「何を伝えるためのものか」が明確か。非エンジニアも含め、想定読者と前提知識が分かるか。 |
| 2 | スコープ（範囲）の明示 | 何を扱い、何を扱わないのかが明確か。過剰な期待や誤解を生まない内容になっているか。 |

📖 使い方

基本的なワークフロー

Step 0: ドキュメントを作成

• レビューしたいドキュメント（.md）を作成

Step 1: 初期配置

• 01-draft/フォルダにドキュメントを格納

Step 2: Clineに初期命令

プロセス定義（process-definition.md）を確認し、レビューを開始してください

Step 3: Clineの提案を確認

• Clineがガイドラインの項目を確認し、レビュー計画を提示
• 項目1から順番に実行することを確認

Step 4: レビューループ

各ガイドライン項目ごとに以下を繰り返し：

1. Clineがレビュー実行

   • 該当項目の観点でドキュメントを分析

2. 指摘がない場合

   • 次の項目へ進む

3. 指摘がある場合

   • Clineが指摘と修正方針案を02-issues-and-proposals/に保存
   • ユーザーが修正方針案を確認・承認
   • Clineが修正版を03-revised/に作成
   • ユーザーが修正版を確認・承認

Step 5: 完了

• 全項目のレビュー完了後、最終版を04-final/に格納
• レビューサマリーを自動生成

レビューの中断と再開

中断する場合:

レビューを中断してください

再開する場合:

レビューを再開してください

レビュー進捗はreview-status.jsonに自動保存されるため、いつでも続きから再開できます。

📂 フォルダ構造

technical-writing-review-workflow/
├── README.md                      # このファイル
├── LICENSE                        # ライセンス情報
├── process-definition.md          # プロセス定義（Clineが読み込む）
├── review-status.json             # レビュー進捗（自動生成）
├── workflow-diagram.svg           # ワークフロー図
│
├── guidelines/                    # ガイドライン
│   └── sample-guideline.md
│
├── 01-draft/                      # 初版（レビュー前）
├── 02-issues-and-proposals/       # 指摘・修正方針案
├── 03-revised/                    # 修正版
└── 04-final/                      # 最終版

🔧 カスタマイズ

ガイドラインのカスタマイズ

guidelines/sample-guideline.mdを編集するか、独自のガイドラインファイルを作成：

| 項目番号 | レビュー観点 | 観点説明 |
|---------|------------|---------|
| 1 | あなたの観点 | 説明 |
| 2 | あなたの観点 | 説明 |

Clineは表形式を自動的に解析してレビューを実行します。

プロセスのカスタマイズ

process-definition.mdを編集して、レビュープロセスをカスタマイズ可能です。

❓ FAQ

Q1: Clineが指摘を見落とすことはありますか？

A: AIの精度には限界があります。重要なドキュメントは、AIレビュー後に人間による最終確認を推奨します。

Q2: 商用利用できますか？

A: はい、MITライセンスのため自由に利用できます。

📝 Notes

本リポジトリは、特定の組織や企業の内部プロセスを示すものではありません。 一般的なテクニカルライティングレビューの考え方を、再利用可能な形で整理したものです。

利用者の文脈や目的に応じて、自由に簡略化・拡張してください。

📄 ライセンス

このプロジェクトはMITライセンスの下で公開されています。詳細はLICENSEファイルをご覧ください。