「AIに書かせた文章、なんかAI臭くない?」を終わらせる — kotonohaのAgent Skillsに学ぶドキュメント自動生成の設計

「AIに書かせたREADME、なんか薄っぺらい」「文章は綺麗だけど内容が浅い」「いかにもAIが書いた感じの言い回しが鼻につく」——生成AIでドキュメントを作らせたことがある人なら、一度はこの壁にぶつかったはずです。

本記事では、この課題を「構造」と「文章」を分離して解決するAgent Skills設計を、実際のリポジトリ kotonoha の中身を見ながら解説します。単なるプロンプト工夫ではなく、役割分担されたスキル群でAIに文書を書かせる設計パターンが主題です。

Note: この記事自体も、kotonohaのtech-writer（Qiita記事フォーマットへの構造化）とjapanese-prose（日本語の文章磨き込み）を使って執筆しています。つまり本記事は、これから解説する仕組みの「動く実例」でもあります。

環境 / 前提

• GitHub Copilot CLI（Agent Skills対応）
• kotonohaリポジトリの .github/skills/ 配下に3つのSkillが同梱
  • tech-writer（構造担当）
  • japanese-prose（文章担当、GiNZAベース）
  • presentation-planner（プレゼン設計担当）

補足として、資料作成の過程でWebから情報収集が必要になる場面がありますが、kotonoha自体は独自の検索エンジンやクローラーを実装していません。Web検索・ページ取得はホストであるGitHub Copilot CLIが標準で備えるスキル（web_search / web_fetch）にそのまま委譲します。これはpresentation-plannerがPPTXバイナリ生成を自前実装せず専用スキルに委譲するのと同じ思想で、「餅は餅屋」——各Skillは自分の責任範囲（構造・文章・設計）だけに徹し、汎用的な機能はホスト側の既存能力を再利用する、という一貫した設計方針です。

なぜAI生成文章は「AI臭く」なるのか

AIにドキュメントを書かせると、多くの場合、次の2つの問題が同時に発生します。

1. 構造の問題: 見出しが「概要」「詳細」のように内容を予告しない、必要な情報（読者・前提・完了条件）が抜けている
2. 文章の問題: 「〜することができます」「〜と言えるでしょう」のような定型表現の多用、冗長な言い回し、読みにくい係り受け

多くのツールはこの2つを一度に「良い感じに」処理しようとして、どちらも中途半端になります。kotonohaはここを明確に分離しているのが特徴です。

kotonohaの設計思想: 構造と文章の責任分界

tech-writer/SKILL.md には、この分離が明記されています。

Document quality splits into two layers: "is the structure right" and "is the prose natural and readable". This skill owns the first layer ... The bundled japanese-prose skill owns the second layer

判定の目安も具体的です。

• 見出しを1つ消しても文書として成立するか → 構造の問題（tech-writer担当）
• 1文だけ読み直すと意味が変わるか → 文章の問題（japanese-prose担当）

この線引きにより、それぞれのSkillが自分の責任範囲だけに集中でき、AIが「構造もいじりつつ文章も直す」ような曖昧な作業をしなくなります。

Skill 1: tech-writer — 「何を書くか」を決める

tech-writer はREADME、設計書、要件定義書、Qiita/Zenn記事など18種類のドキュメント種別をサポートします。特徴的なのは書き始める前の情報収集フローです。

1. リクエストからドキュメント種別を特定（曖昧なら最初の質問にする）
2. 該当するreferenceファイルを開き、「書く前に確定すべき項目」を確認
3. 一度に1問だけ質問し、回答を待つ
4. 最低限「読者」「読了後のゴール」「種別」「種別固有の必須項目」が揃うまで続ける
5. "わからない/該当なし" という回答も、条件を満たしたとみなす
6. 揃ったら、ユーザーに何かを書かせるのではなく、AI自身が集めた回答から統合して即座に執筆に入る

これは単なるテンプレート穴埋めではなく、「情報が足りないまま書き始めて後で破綻する」ことを防ぐインテークループです。長文になりがちなドキュメント（設計書、要件定義書など）では、本文を書く前に見出しだけの目次を作り、「読者の視点で見出しだけ読んで内容を予測できるか」をレビューしてから初めて本文執筆に進みます。

最大の特徴: 情報が足りなければAIが「聞き返す」

kotonohaの tech-writer で最も実務的に効くのが、この聞き返し機能です。多くの生成AIツールは、情報が不足していても「それっぽい」ドキュメントを見切り発車で書いてしまい、後から「前提が違う」「読者を誤解していた」と手戻りが発生します。tech-writer はこれを構造的に防いでいます。

SKILL.mdには次のように明記されています。

Requests are often bare goals ("I want to write a README", "○○を書きたい")
without enough context to start. Do not front-load a long questionnaire or
hand the user a checklist to fill in.

つまり、「READMEを書いて」のような曖昧な一言だけでも起動できますが、その裏では以下のルールで必要最小限の聞き返しが走ります。

1. 一問一答方式: 質問票をどさっと渡すのではなく、その時点で最も情報価値の高い質問を1つだけ選んで聞き、回答を待ってから次の質問に進む（Ask exactly one question at a time）
2. 聞く項目は最小限に絞る: 最低でも「誰が読むか」「読んだ後に読者は何ができるようになるか」「ドキュメント種別（サブタイプ含む）」「種別固有の必須項目（例: 設計書なら意思決定と代替案、運用手順書ならRTO/RPO、移行計画ならロールバック条件）」の4点が揃うまで質問を続ける
3. 「わからない」も有効な回答として扱う: 同じ質問をしつこく繰り返さない。ユーザーが「特に決めていない」「該当チケットはない」と答えたら、それを文書内の「未確定事項」として記録し、質問はそこで打ち切って先に進む
4. すでに答えている情報は聞き直さない: 最初のリクエストで既に「読者は新人エンジニア」のように情報が含まれていれば、その質問はスキップする
5. 情報が揃った後はユーザーに執筆させない: 質問が完了したら、集めた回答をAI自身が統合し、そのまま本文執筆に入る。「では下書きをお願いします」とユーザーに丸投げすることはない

つまりこの仕組みは、「AIが賢く先回りして質問責任を持つ」 設計です。ユーザーは長いテンプレートやチェックリストを埋める必要がありません。対話しているだけで、気づけば必要な情報が揃っている、という体験になります。presentation-planner にも同様の一問一答インテーク（対象読者・目的・場面・素材・言語やアスペクト比・既存テンプレートの有無を1つずつ確認）が実装されており、kotonoha全体を貫く共通パターンになっています。

Qiita記事向けには専用のdoctypeリファレンスもあり、以下を要求します。

• フロントマターの title / tags は必須、private は明示的に選ぶ
• 本文見出し直前のリード文で「この記事が解決する具体的な問題」を明示（Qiitaは検索流入が多いため）
• バージョン・環境情報を手順より前に明記
• トラブルシュート系記事は「結論(解決策)を先に、背景説明は後に」

Skill 2: japanese-prose — 「どう書くか」を磨く

japanese-prose は事実・数値・識別子・コード・文書構造には一切手を触れず、日本語の言い回しだけを磨くスキルです。GiNZA による形態素解析・係り受け解析・固有表現抽出を使い、スコアを機械的に算出します。

採点方式もシンプルです。

検出レベル	減点
critical	-10点
warning	-4点
info	-1点

uv run scripts/lint.py <target-file> --genre tech --json > baseline.json

重要なのは、このスコアが 「品質の証明」ではなく「トリアージの目安」 だと明言している点です。90点以上でも事実誤りはあり得るし、50点台でも全指摘を直す必要はない、とドキュメントに明記されています。AIに機械的スコアだけを信じさせず、文脈判断の責任をAI自身に残す設計思想が徹底されています。

修正ループも野放図には回しません。「編集→再診断」は最大3ラウンドまでとし、収束しなければ「未収束」として未解決項目を正直に報告する、というルールがあります。AIが延々と自己満足の修正を繰り返す事故を防ぐ仕組みです。

仕上げの一手: rubber-duck reviewによる「独立した第三者レビュー」

構造(tech-writer)と文章(japanese-prose)を整えても、書いた本人（AI自身）による自己レビューには限界があります。そこでkotonohaは、write モードの最終工程として必ず独立したレビュアーによるrubber-duck reviewを挟みます。

そもそもrubber-duck reviewとは何か

「ラバーダック・デバッグ（rubber duck debugging）」という手法をご存じでしょうか。誰かに——たとえアヒルの人形相手でも——自分のコードや文書を1から説明すると、説明している最中に自分自身で見落としを発見できる、というものです。rubber-duck reviewはこれをAIエージェントに応用したもので、執筆したAIとは別の主体（第三者）に、完成した文書を最初から説明・レビューさせる工程を指します。

重要なのは、これはkotonohaが自作した仕組みではなく、GitHub Copilot CLIがホストとして提供する rubber-duck エージェントタイプの仕組みだという点です。GitHub Copilot CLIには、実装や計画を読み取り専用でレビューし、些末なスタイルの指摘は無視して、意味のあるバグ・論理破綻・設計上の欠陥だけを報告する rubber-duck という専用のサブエージェント種別が組み込まれています。kotonohaのtech-writerやpresentation-plannerは、このホスト標準のrubber-duckエージェントを呼び出して独立レビューを実行しています。Web検索を自前実装せずホストのweb_search/web_fetchに委譲しているのと全く同じ構図で、「レビューという汎用機能」もホストの既存能力にそのまま乗っかっているわけです。

kotonoha自身のSKILL.mdでは次のように明記されています。

use the host's subagent mechanism to launch an independent reviewer in the
rubber-duck role to challenge the completed document for meaningful
problems that the authoring pass may have missed ... Do not substitute the
author's own self-review: independence is the point of this pass.

ポイントは「執筆したAIとは別の主体にレビューさせる」ことです。具体的な流れは以下の通りです。

1. 文脈をフルで渡す: 対象ファイル、ドキュメント種別、想定読者、§1で決めた「読了後のゴール」、明示済みの制約や前提をレビュアーに渡す
2. 指摘対象を限定する: 誤り・論理破綻・情報の欠落・読者にとっての読みやすさの流れ・具体例・記載すべき制限事項など、実質的な問題だけを報告させる（見た目の好みのような些末な指摘は対象外）
3. 指摘は"編集"で解消する: 単に指摘リストをもらうだけでなく、妥当な指摘は実際に文書を修正して解消する。要件と矛盾する、あるいは事実として的外れな指摘は「却下理由」を1行添えて記録する
4. 修正後は再チェックを回す: 文章に手を入れたら§で述べたjapanese-prose最適化と構造リントをやり直してから、次のレビューラウンドに入る
5. ラウンド数に上限を設ける: 通常文書は最大5ラウンド、コミットメッセージのような単発の成果物は最大3ラウンドまで。「未対応の実質的指摘がゼロ」になった時点でクリーンとみなして終了する
6. 結果を正直に報告する: 独立したレビュアーが使えない場合はreview not performed、上限までに収束しなければreview did not convergeと明示し、「完了した」と偽らない

このrubber-duck reviewは presentation-planner にも同じ思想で組み込まれています（最大5ラウンド、ストーリーの整合性やエビデンスの有無を独立レビュアーがチェック）。「AIが自分で書いて、自分でOKを出す」という自己完結ループを構造的に禁止しているのが、kotonoha全体を貫く一貫した設計です。

Skill 3: presentation-planner — スライドは「書く」前に「設計する」

ドキュメントではなくPPTXが対象ですが、考え方は同じです。「バイナリを生成する前に、構成・ストーリー・デザインを確定する」 ことに徹し、PPTX生成そのものは別スキルに委譲します。

生成する成果物は5点セット。

• presentation-brief.md（対象読者・目的・制約）
• presentation-scenario.md（ストーリーの起伏）
• slide-outline.md（1スライド1メッセージの表形式アウトライン）
• design-spec.yaml（デザイン仕様）
• pptx-handoff.md（実装スキルへの引き継ぎ書）

ここでも「タイトルだけ拾い読みして主張が再現できるか」「各スライドがストーリーの段階に対応しているか」というレビュー観点が明文化されています。AIに"それっぽいスライド"を作らせず、監査可能な中間成果物を必ず経由させるという一貫した思想です。

3つのSkillから見える、AIにドキュメントを書かせるコツ

kotonohaの設計から抽出できる、汎用的に使える原則は次の4つです。

1. 情報が足りなければAIが自分から聞き返す — 見切り発車で書かせず、読者・ゴール・種別固有の必須項目が揃うまで一問一答で埋める。ユーザーに質問票を渡すのではなく、AI側が「次に何を聞くべきか」を判断する。
2. 「構造」と「文章」を別工程にする — 同じプロンプトで両方を頼むと、どちらも中途半端になりやすい。まず骨格を固め、文章の磨き込みは別パスにする。
3. 機械的スコアは"トリアージ"であって"合格ライン"ではない — 定量指標を過信せず、最終判断は文脈を踏まえて人（またはAI自身）が下す前提を明記する。
4. 最後は自分以外に見せる — 書いたAI自身の自己採点で完了と言わせず、独立したrubber-duckレビュアーに実質的な問題だけを指摘させ、ラウンド上限を決めて収束させる。

まとめ

AIにドキュメントを書かせて「なんかAI臭い」と感じたら、それはプロンプトの語彙の問題ではなく、構造決定と文章推敲を同時に一つのAIに丸投げし、しかも自己レビューだけで完結させていることが原因かもしれません。kotonohaのAgent Skillsは、①書く前の一問一答インテーク、②構造と文章の分離、③機械診断と文脈判断の使い分け、④独立レビュアーによるrubber-duck reviewを仕組み化し、AI生成文書の質を体系的に底上げしています。なお、Web検索のような汎用機能は自前実装せずホスト（GitHub Copilot CLI）のスキルにそのまま委譲する点も、「餅は餅屋」を貫く一貫した設計思想を表しています。

自分のプロジェクトでAgent Skillsやプロンプトチェーンを設計する際も、「このAIタスクは構造の話か、文章の話か」「レビューは誰が行うのか」を一度立ち止まって切り分けてみると、精度が変わるはずです。

参考

• kotonoha リポジトリ: .github/skills/tech-writer/, .github/skills/japanese-prose/, .github/skills/presentation-planner/
• GiNZA