- ブログの品質管理は面倒くさい
- 書籍の執筆で痛感した修正コスト
- AIが加わると修正サイクルが回る
- スキルでAIに品質基準を教え込む
- サブエージェントで「執筆チーム」を作る
- 執筆チームの動き方
- 執筆チームの使い方
- スキルは使いながら育てる
- ブログだけじゃない。開発ドキュメントでも使える
- まとめ
エンジニアの関口です。
ブログ記事を書いて、textlintでチェックして、エラーを手で直して、また書いて。この繰り返しに疲れたことはありませんか。
私はCursorのAgent Skillsとサブエージェントを組み合わせて、ブログ執筆の「チーム体制」を作りました。1人で全部やっていた執筆作業を、AIのサブエージェントに役割分担させています。この記事では、textlintとAIの相性のよさと、サブエージェントで執筆チームを構成する方法を紹介します。
ブログの品質管理は面倒くさい
技術ブログを書いていると、品質管理が地味に手間です。
textlintを導入すれば、文章の品質チェックは自動化できます。npm run textlintでチェックし、--fixで自動修正する。ここまでは問題ありません。
ただし、自動修正できない指摘が残ります。
- 「文が長すぎる」
- 「受動態を能動態にすべき」
- 「冗長な表現がある」
こういった指摘は、前後の文脈を読みながら手作業で直す必要があります。1記事あたり10件、20件とエラーが出ると、1つずつ確認して直す作業に時間がかかります。修正すると前後の文脈も調整が必要になり、億劫になって記事の公開を先延ばしにすることもありました。
書籍の執筆で痛感した修正コスト
この問題を強く感じたのは、書籍やオンライン教材を執筆したときです。
どちらの執筆でもtextlintで品質管理をしていました。ローカルで通ったのでPRを出す。終わったと思ったら、CIでtextlintのエラーが走って差し戻される。そんな経験を何度もしました。
書籍の場合、1章あたり数十件のエラーが出ます。1つ直すと前後の文脈も調整が必要になり、修正作業だけで数時間かかることもありました。
textlintの「検出」は優秀です。ただ、検出された問題を文脈に合わせて直す工程は、どうしても人間の手作業が必要でした。
修正コストの問題はそれだけではありません。textlintでは拾えない問題もあります。「この文脈だと読者に伝わりづらい」「前提知識の説明が足りない」といった「伝わりやすさ」の調整です。こちらは自分の知識と文章力だけが頼りでした。書いて、読み返して、調整する。この繰り返しにも膨大な時間がかかっていました。
AIが加わると修正サイクルが回る
textlintの「検出」とAIの「修正」を組み合わせると、状況が変わります。
以前は手で直していた「文の分割」「言い回しの修正」を、AIが文脈を理解した上で一気に直してくれます。textlintのエラー10件程度であれば、まとめて渡して数秒で修正が返ってきます。
「伝わりやすさ」の調整も同じです。「この文脈だと読者へ伝わりづらいので、補足を入れてほしい」「前提知識を考慮して、もう少しかみ砕いてほしい」と依頼できます。自分の頭の中にある知識を、読者へ届く形に変換する部分をAIが補完してくれます。
ただ、ここまでは「自分とAIの1対1」の話です。ここからが本題です。
スキルでAIに品質基準を教え込む
AIに記事を整形してもらう際、毎回「見出しはh3から始めて」「AIっぽい表現は避けて」と指示するのは面倒です。そこでAgent Skillsを使います。
Agent Skillsは、AIエージェントに「必要な時に必要な知識だけを読み込ませる」仕組みです。.cursor/skills/my-skill/SKILL.mdの形式でスキルを定義しておくと、タスクに関連すると判断した場合に自動で読み込みます。
私ははてなブログ用のスキルを作り、見出しルール、文章品質の基準、AIっぽい表現の排除ルールなどを定義しています。また、textlintとの連携ルールも含めており、スキルが「生成時の品質担保」、textlintが「生成後の品質検証」を担う2段構えにしています。
品質検証で利用しているtextlintのプリセットは以下の2つです。
- textlint-rule-preset-ja-technical-writing : 技術文書向けのルールプリセット。1文の長さ、同じ助詞の連続、冗長な表現など23のルールがまとまっている
- @textlint-ja/textlint-rule-preset-ai-writing : AI生成文章によくある誇張表現や機械的なリスト記法を検出するプリセット。AIっぽさを消したいときに有効
preset-ja-technical-writingは技術文書の基本品質を担保し、preset-ai-writingはAIに書かせた文章から「AIっぽさ」を取り除く役割です。この2つを組み合わせることで、文章の基本的な品質とAI特有の表現の両方をカバーできます。preset-ai-writingの詳細については、textlint-rule-preset-ai-writingを試すの記事が参考になります。
スキルの詳細や作り方については、以前Zennに書いた記事を参照してください。
サブエージェントで「執筆チーム」を作る
スキルで品質基準を定義するだけでも効果はあります。ただ、それはあくまで「自分とAIの1対1」の延長です。
Cursorにはサブエージェント機能があります。親エージェントのタスクを分割して、独立したエージェントが並行で処理する仕組みです。カスタムサブエージェントは.cursor/agents/配下に.mdファイルを置くことで定義できます。
この仕組みを使って、ブログ執筆に特化した「執筆チーム」を作りました。
チーム構成
.cursor/agents/ ├── textlint-checker.md # 品質の検証担当 ├── reader-reviewer.md # 伝わりやすさ担当 └── hatena-formatter.md # フォーマット担当
親エージェント（自分が直接やりとりするAI）が記事本文の執筆に集中し、3つのサブエージェントが並行で動きます。
textlintチェッカー（品質の検証担当）
記事ファイルに対してnpx textlintを実行し、エラー内容を報告する役割です。自動修正できるものは先に--fixで直し、残ったエラーを修正案とともに親エージェントに返します。
親エージェントが記事を整形している間に、裏でtextlintを走らせることができます。整形が終わった時点でチェック結果も揃っているので、すぐに修正へ進めます。
textlint-checker.md のプロンプト全文
# textlintチェッカー ブログ記事のMarkdownファイルに対してtextlintを実行し、エラー内容を報告するサブエージェント。 ## 役割 記事の品質検証を担当する。親エージェントが記事を整形している間に、並行してtextlintチェックを実行する。 ## 手順 1. 対象ファイルのパスを受け取る 2. `npx textlint "<ファイルパス>"` を実行する 3. エラーがあれば、エラーの行番号・内容・ルール名・修正案を報告する 4. `npx textlint --fix "<ファイルパス>"` で自動修正できるものは先に修正する 5. 自動修正後、再度 `npx textlint "<ファイルパス>"` を実行して残りのエラーを報告する ## 使用するルール - `textlint-rule-preset-ja-technical-writing` : 技術文書の品質チェック - `@textlint-ja/textlint-rule-preset-ai-writing` : AIっぽい表現の検出 ## 注意事項 - チェック結果はそのまま親エージェントに返す - 自動修正を実行する前に、必ず元のファイルの内容を把握しておく - `preset-ai-writing` のエラーは特に注意して報告する（AIっぽさの除去が目的のため）
読者目線レビュアー（伝わりやすさ担当）
記事を「読者の立場」で読み、伝わりづらい箇所を指摘する役割です。textlintでは検出できない「伝わりやすさ」の問題を拾います。
レビュー観点は4つあります。
- 専門用語が初出で説明なく使われていないか（前提知識の確認）
- セクション間の論理的なつながりがあるか（文脈のつながり）
- 抽象的な説明だけで終わっていないか（具体性）
- 読者が記事を読んだ後に何をすべきか明確になっているか（行動につながる）
ファイルの編集はせず、指摘と改善案の報告のみを行います。
reader-reviewer.md のプロンプト全文
# 読者目線レビュアー ブログ記事を「読者の立場」で読み、伝わりづらい箇所や前提知識の不足を指摘するサブエージェント。 ## 役割 記事の「伝わりやすさ」を担当する。技術的な正確性ではなく、読者にとって理解しやすいかどうかを評価する。 ## レビュー観点 ### 前提知識の確認 - 専門用語が初出で説明なく使われていないか - 読者が知らない可能性のある概念に補足があるか - 略語やツール名の正式名称が示されているか ### 文脈のつながり - セクション間の論理的なつながりがあるか - 話題が唐突に変わっていないか - 前の段落で述べたことと矛盾していないか ### 具体性 - 抽象的な説明だけで終わっていないか - 具体例やコード例が適切に添えられているか - 「便利です」「効果があります」のような曖昧な表現に根拠があるか ### 読者の行動につながるか - 読者が記事を読んだ後に何をすべきか明確か - 再現可能な手順が示されているか - 参考リンクやリソースが提示されているか ## 注意事項 - 技術的な正誤ではなく「伝わるかどうか」に集中する - 読者のペルソナは「エンジニアだが、記事のテーマについては初学者」を想定する - 指摘は具体的に。「わかりにくい」だけでなく「なぜわかりにくいか」も添える - ファイルの編集はしない。指摘と改善案の報告のみを行う
はてなブログフォーマッター（フォーマット担当）
はてなブログのMarkdownモードに準拠しているかをチェックし、フォーマットを修正する役割です。記事の内容には手を加えません。
見出しがh2から始まっているか、[:contents]が冒頭にあるか、コードブロックに言語指定があるかを確認します。h1が使われていた場合は自動でh2に変換します。
hatena-formatter.md のプロンプト全文
# はてなブログフォーマッター ブログ記事がはてなブログのMarkdownモードに準拠しているかをチェックし、フォーマットを修正するサブエージェント。 ## 役割 はてなブログのフォーマット準拠を担当する。記事の内容には手を加えず、フォーマットのみを修正する。 ## チェック項目 ### 見出しの構造 - h1が使われていないか - 見出しがh2から始まっているか - 見出しの階層が守られているか（h2 → h3 → h4の順） ### 目次記法 - `[:contents]` が記事冒頭に配置されているか ### Markdown基本 - 段落ごとに空行が入っているか - コードブロックに言語指定があるか - リストのインデントが正しいか ## 修正ルール - `# 見出し` → `## 見出し` に変換する - `[:contents]` が欠落している場合、フロントマターの直後に挿入する - フロントマター（`---` で囲まれた部分）は変更しない ## 注意事項 - 記事の内容（文章そのもの）は変更しない - フォーマットの修正のみを行う - 修正したら必ず差分を報告する
執筆チームの動き方
「記事を書いて」と依頼すると、4つのエージェントがそれぞれの役割で動きます。
| 役割 | 担当 | やること |
|---|---|---|
| 漫画家（自分） | 親エージェント | 構成の決定、本文の執筆と整形 |
| アシスタントA | textlintチェッカー | 品質の検証と自動修正 |
| アシスタントB | 読者目線レビュアー | 伝わりやすさの評価と指摘 |
| アシスタントC | はてなブログフォーマッター | フォーマットの準拠チェックと修正 |
テーブルの「親エージェント」について補足します。
親エージェントとは何か
親エージェントとは、Cursorのエージェントモードで自分が直接やりとりしているAIのことです。チャットウィンドウで「この記事を書いて」と依頼したときに応答しているAIが、そのまま親エージェントにあたります。特別な定義ファイルを作る必要はありません。
親エージェントはスキル（.cursor/skills/）の品質基準に沿って記事を書きつつ、サブエージェント（.cursor/agents/）にタスクを振ります。関係を図にすると以下のようになります。
自分（人間）
└── 親エージェント（Cursorのエージェントモード）
├── textlintチェッカー（サブエージェント）
├── 読者目線レビュアー（サブエージェント）
└── はてなブログフォーマッター（サブエージェント）
自分がやることは、親エージェントに「何を書くか」を伝えることです。あとは親エージェントがタスクの内容を判断して、サブエージェントを並行で起動してくれます。
サブエージェントはそれぞれ独立したコンテキストで動きます。親エージェントの作業を邪魔せず、結果だけを返してくれる仕組みです。漫画家のたとえでいうと、アシスタントが別の机で作業して、完成した原稿だけを漫画家に渡すイメージです。
手動で「書く → チェックする → 直す → 再チェックする」を繰り返していた工程を、この並行処理で短縮できます。自分はアウトラインと伝えたいメッセージを考えることに集中して、品質チェックやフォーマット、読者目線のレビューはチームに任せる。この分業がサブエージェントで実現できます。
執筆チームの使い方
実際にどう使うのか、具体的な流れを紹介します。
1. メモとアウトラインを自分で用意する
私はObsidianで日々のメモをストックしています。記事のテーマが決まったら、関連するメモを集めてアウトラインを作ります。「何を伝えたいか」「どういう順番で説明するか」は自分の頭で考えます。
ここが漫画家でいう「ネーム」の工程です。AIに丸投げしているわけではありません。
2. Cursorに記事の執筆を依頼する
アウトラインとメモをCursorに渡して「この内容ではてなブログの記事を書いて」と依頼します。すると、親エージェントが記事本文の整形を始めると同時に、サブエージェントが並行で動き始めます。
- 親エージェント: スキルの基準に沿って記事を整形する
- textlintチェッカー: 整形された記事に対して
npx textlintを実行する - はてなブログフォーマッター: 見出し構造や目次記法を確認する
3. レビュー結果を受け取って修正する
textlintチェッカーがエラーを報告し、読者目線レビュアーが「ここは伝わりづらい」と指摘を返してきます。親エージェントがそれらの結果を受け取り、まとめて修正します。
自分がやることは、修正結果を確認して「もうちょっとこう直して」と追加指示を出すことだけです。
4. 最終確認して公開する
修正後、再度textlintを実行して問題がないことを確認します。最後に自分で読み返して「自分の言葉になっているか」をチェックしてから公開します。
この最終チェックだけは省略しません。AIが書いた文章をそのまま出すのではなく、自分の言葉として違和感がないかを確認する工程です。
スキルは使いながら育てる
スキルやサブエージェントは、一度作って終わりではありません。記事を書くたびにアップデートしています。
- AIが生成した文章を読み返して「自分っぽくない」と感じたら、その表現を禁止パターンに追加する
- 「こういう書き方のほうが自然だ」と思ったら、推奨パターンとして追記する
- 読んでも意味のわからない文章は、回りくどい表現として禁止する
- サブエージェントのレビュー観点が足りなければ、
.mdファイルに追記する
日々のフィードバックを反映することで、チーム全体の精度が上がっていきます。
ブログだけじゃない。開発ドキュメントでも使える
今回はブログ執筆の文脈で紹介しましたが、この「執筆チーム」の考え方は開発現場のドキュメント作成にも応用できるのではないかと考えています。
開発していると、ドキュメントを書く場面は意外と多いです。
- 設計ドキュメント
- API仕様書
- 手順書やRunbook（障害対応や定型作業の手順をまとめたドキュメント）
- 障害報告書
- チーム内のナレッジ共有
これらのドキュメントも、ブログ記事と同じ課題を抱えています。書いた後の品質チェックが面倒で後回しにしたり、専門用語の説明が不足していて読む人に伝わらなかったりする。
サブエージェントの役割を入れ替えれば、開発ドキュメント用の執筆チームを作れます。たとえば以下のような構成です。
- textlintチェッカー → そのまま使える
- 読者目線レビュアー → 「新メンバーが読んで理解できるか」の観点に変える
- はてなブログフォーマッター → 社内Wikiやリポジトリの
.mdフォーマットに差し替える
.cursor/agents/配下の.mdファイルを書き換えるだけなので、チーム編成の変更は手軽です。ブログ用と開発ドキュメント用の執筆チームを、プロジェクトごとに切り替えて運用できます。
まとめ
textlintとAIは相性がよいと感じています。
textlintは「ルールに基づいた機械的な検出」が得意です。ただ、検出された問題を文脈に合わせて直す工程は、人間の手作業が必要でした。書籍の執筆では、この修正作業だけで数時間かかっていました。
ここにAIが入り、さらにサブエージェントで役割を分けることで、1人でやっていた執筆作業がチーム体制になります。
サブエージェントを3つ並べて記事を書いていると、売れっ子の漫画家がアシスタントに背景やトーンを任せている気分になります。自分はネーム（構成とメッセージ）に集中して、品質チェックやフォーマット、読者目線のレビューはスタッフが並行で進めてくれる。1人で全部やっていた頃には戻れません。
ブログを書くハードルを下げたい方は、まずtextlintとAIの組み合わせから試してみてください。そこにサブエージェントを足せば、自分だけの執筆チームが手に入ります。
www.yayoi-kk.co.jp
弥生のエンジニアに関するnote記事もご覧ください。
note.yayoi-kk.co.jp
