技術記事執筆スキル
技術記事の執筆をユーザーと対話しながら6つのフェーズで進めるスキルです。
基本原則
ピラミッド原則
- •結論を先に述べ、その後に根拠・詳細を展開する
- •読者は最初に「何が言いたいのか」を把握できる
- •詳細は「結論→キーポイント→詳細情報」の階層構造で整理する
SCQAフレームワーク
記事の導入部を構成するフレームワーク：
- •S (Situation): 読者が共感できる現状・背景
- •C (Complication): 状況を脅かす課題や問題
- •Q (Question): 読者が持つべき問い
- •A (Answer): 提案する解決策・結論（＝記事の主題）
詳細は references/pyramid-scqa-guide.md を参照。
6フェーズワークフロー
Phase 1: 目的と読者の確認
目的: 記事のゴールと想定読者を明確にする
エージェントの質問例:
- •「この記事で読者に何を伝えたいですか？」
- •「想定読者はどのような人ですか？（例：初心者、中級者、特定技術の経験者）」
- •「読者がこの記事を読む前に知っておくべき前提知識はありますか？」
- •「読者が記事を読み終わった後、どのような状態になっていてほしいですか？」
完了条件: 以下が明確になったらPhase 2へ進む
- •記事のゴール（1文で表現）
- •想定読者像
- •前提知識
- •読了後の期待状態
成果物の記録形式:
<!-- ## 目的定義 - ゴール: [記事のゴール] - 想定読者: [読者像] - 前提知識: [必要な前提知識] - 読了後の状態: [期待する状態] -->
Phase 2: SCQA導入部の設計
目的: 読者を自然に本題へ導く導入部を設計する
エージェントの質問例:
- •「読者が現在置かれている状況・背景は何ですか？（Situation）」
- •「その状況において、どのような課題や問題が発生していますか？（Complication）」
- •「読者が抱くであろう疑問は何ですか？（Question）」
- •「その疑問に対する答え（この記事の結論）は何ですか？（Answer）」
完了条件: S/C/Q/Aの4要素がすべて定義されたらPhase 3へ進む
成果物の記録形式:
<!-- ## SCQA - Situation: [状況] - Complication: [問題] - Question: [疑問] - Answer: [答え/結論] -->
Phase 3: ピラミッド構造でセクション構成
目的: 記事全体のアウトラインをピラミッド構造で設計する
エージェントの進め方:
- •Phase 2のAnswerを記事の「結論」として確認
- •結論を支える「キーポイント」を3〜5個程度洗い出す
- •各キーポイントを1セクションとして構成
- •各セクション内で扱う詳細トピックを列挙
エージェントの質問例:
- •「結論『[Answer]』を支える主要なポイントは何ですか？」
- •「それぞれのポイントについて、どのような詳細を説明しますか？」
- •「セクションの順序はこれでよいですか？依存関係はありますか？」
完了条件: 以下が確定したらPhase 4へ進む
- •セクション一覧（タイトルと概要）
- •各セクションの詳細トピック
- •セクションの順序
成果物の記録形式:
<!-- ## アウトライン ### 導入 - SCQA形式で問題提起と結論を提示 ### セクション1: [タイトル] - [詳細トピック1] - [詳細トピック2] ### セクション2: [タイトル] - [詳細トピック1] - [詳細トピック2] ### まとめ - 結論の再確認 - 次のアクション -->
Phase 4: 各セクションの執筆
目的: セクション単位で執筆→レビュー→修正のループを回す
エージェントの進め方:
- •アウトラインの最初のセクションから順に執筆
- •1セクション執筆したらユーザーにレビューを依頼
- •フィードバックを受けて修正
- •ユーザーがOKを出したら次のセクションへ
- •すべてのセクションが完了するまで繰り返す
各セクション執筆時の確認事項:
- •ピラミッド原則にしたがっているか（結論→根拠→詳細）
- •想定読者のレベルに合っているか
- •前のセクションとの繋がりは自然か
- •コード例が必要な場合は含まれているか
エージェントのレビュー依頼例:
「[セクション名]」を執筆しました。 [執筆した内容] 以下の点についてフィードバックをお願いします： 1. 内容は期待通りですか？ 2. 追加・削除したい情報はありますか？ 3. 表現や説明の仕方で気になる点はありますか？ 問題なければ「OK」と言っていただければ次のセクションに進みます。
完了条件: すべてのセクションがユーザー承認を得たらPhase 5へ進む
Phase 5: 全体の推敲
目的: 記事全体の品質を向上させる
エージェントのチェック項目:
- •
一貫性チェック
- •用語の統一（同じ概念に異なる言葉を使っていないか）
- •文体の統一（です/ます調、である調の混在がないか）
- •時制の統一
- •
冗長表現の削除
- •不要な繰り返し
- •「〜することができる」→「〜できる」
- •「〜という」の多用
- •
読者視点でのレビュー
- •導入から結論まで論理が通っているか
- •飛躍している説明はないか
- •専門用語に説明が必要か
- •
技術的正確性
- •コード例は動作するか
- •バージョン情報は正確か
- •リンクは有効か
エージェントの報告形式:
全体を推敲しました。以下の点を修正・改善しました： ### 修正箇所 1. [修正内容1] 2. [修正内容2] ### 確認が必要な箇所 1. [確認事項1] 全体を通して読んでいただき、最終確認をお願いします。 問題なければ「OK」と言っていただければPhase 6（公開設定）に進みます。
完了条件:
- •推敲が完了しユーザーが最終承認
- •HTMLコメント（目的定義、SCQA、アウトライン）を削除
Phase 6: Zenn frontmatterの設定
目的: Zenn投稿用のメタデータを設定する
エージェントの質問例:
- •「記事のタイトルを決めましょう。現在の内容から以下を提案しますが、いかがですか？」
- •提案例を3つ程度提示
- •「記事を表す絵文字を選んでください。提案:［絵文字候補］」
- •「記事のタイプを選んでください: tech（技術記事）/ idea（アイデア）」
- •「トピック（タグ）を最大5つ選んでください。提案:［トピック候補］」
- •「公開設定: true（公開）/ false（下書き）どちらにしますか？」
Zenn frontmatter形式:
--- title: "[記事タイトル]" emoji: "[絵文字]" type: "tech" # tech: 技術記事 / idea: アイデア topics: ["topic1", "topic2", "topic3"] published: false ---
完了条件: frontmatterが記事の先頭に追加され、ユーザーが確認したら完了
フェーズ間の移行
各フェーズの完了時、エージェントは以下を確認する：
Phase [N] が完了しました。 【このフェーズの成果】 [成果の要約] Phase [N+1]「[フェーズ名]」に進んでよろしいですか？
ユーザーが「OK」「進んで」「次へ」などと応答したら次のフェーズへ進む。 ユーザーが修正を求めた場合は、現在のフェーズ内で対応する。
中断・再開
途中で中断する場合、エージェントは現在の進捗状況をHTMLコメントとして記事ファイルに記録する：
<!-- ## 進捗状況 - 現在のフェーズ: Phase [N] - 完了済み: Phase 1, 2, ... - 次のアクション: [次にやること] -->
再開時はこのコメントを読み取り、続きから進める。