| name | tech-article-structure |
| description | 日本語の技術記事を「どの骨格で組むか」から設計するスキル。@trq212（Claude Codeチーム）の記事群から抽出した『記事タイプ A/B/C 分類 → ストーリーパターン選択 → 記事専用アウトライン生成 → 本文ドラフト』のワークフローを提供する。Use this skill whenever the user wants to 技術記事・ブログ・Zenn記事を書きたい、特に「構成が決まらない」「どう書き出せばいいかわからない」「アウトライン・骨組みを作ってほしい」「実践ガイドにするか教訓記事にするか迷う」「ストーリー展開を考えたい」「目次を設計して」というニュアンスを含むとき。テーマだけ決まっていて構成が固まっていない段階の壁打ちに最適。声・主張のトーンに特化した opinionated-tech-writing、課題解決ナラティブ整理の zenn-article-writer とは別軸で、こちらは『記事の構造設計』を担う。3つを組み合わせてもよい。 |
Tech Article Structure — 技術記事の構成設計
技術記事を書くとき、多くの人が詰まるのは文章力ではなく 「この題材をどの骨格で組めばいいか」 です。同じ題材でも、実践ガイドとして書くか、教訓記事として書くか、プロダクト紹介として書くかで、読者に残るものがまったく変わります。
このスキルは、@trq212（Claude Code チーム）の技術記事を分析して抽出した 記事タイプの分類・ストーリーパターン・アウトライン雛形 を使い、題材から「記事専用の骨格」を設計し、承認を得てから本文ドラフトまで書き上げます。
声・主張の強さは opinionated-tech-writing、課題解決ナラティブの整理は zenn-article-writer が担います。本スキルは 構造（骨格） が担当領域です。題材によっては「構造はこのスキル、冒頭の主張は opinionated」のように組み合わせると効果的です。
ワークフロー
ユーザーが題材を持ってきたら、次の順に進めます。各ステップを飛ばさないことが、骨格のズレを防ぎます。
ステップ1 — 題材を理解し、記事タイプを判定する
まず題材について最低限を把握します（既に会話にある情報は再質問しない）。
- 何について書くか（技術・ツール・経験）
- 読者に何を持ち帰ってほしいか（使い方？ 設計思想？ 存在を知ってほしい？）
- 自分の実体験・失敗・数値があるか
これを踏まえ、3タイプのどれかに分類します。判定の指針：
| 読者に渡したいもの | タイプ | 代表的な題材 |
|---|
| 「いつ・どう使うか」の判断基準 | A — 実践ガイド | ツールの使い方、運用ノウハウ、使い分け |
| 「何を学んだか・なぜそう設計したか」 | B — エンジニアリング教訓 | 開発の振り返り、設計判断、ハマりどころ |
| 「こんなものがある」という存在と再現手順 | C — プロダクト紹介 | 自作ツール・機能のお披露目、デモ |
迷ったら、「読者が読み終えて最初に取る行動」 で決めます。設定を変える＝A、自分の設計を見直す＝B、インストールして試す＝C。複数に跨る大型記事は、主軸を1つ選んで他を従属させます。
タイプの詳細なアウトラインと早見表は references/article-types.md を参照してください。
ステップ2 — ストーリーパターンを1つ選ぶ
1記事につき ストーリーパターンを1つ 選びます。複数混ぜると焦点がぼやけます。
- 違和感→転換→新常識 — 「みんな○○している。でも私は△△で限界を感じた」から入る（タイプA向き）
- 決断フレーム — 自然な選択肢を認めつつ「一つ選ぶなら」で代替を推す（タイプA、選択肢が複数あるとき）
- 直感 vs 制約 → 設計 — エンジニアの直感とシステム制約の対立から設計解を導く（タイプB向き）
- Attempt 連載 — 試行1→失敗理由→試行2→…→最終解、と失敗を隠さず並べる（タイプB、試行錯誤があるとき）
- 比喩で世界観を固定 — 1記事1比喩で抽象概念を掴ませる（B/C、概念が難しいとき）
各パターンの詳細・使いどころ・1記事1比喩のコツは references/story-patterns.md にあります。
ステップ3 — 記事専用アウトラインを提示し、承認を得る
選んだタイプの雛形（assets/outline-templates.md）をベースに、この記事専用 に肉付けしたアウトラインを作ります。汎用雛形のコピペで終わらせず、題材固有の見出し・入れるべき具体例・コピペ用プロンプトの置き場所まで落とし込みます。
提示するもの：
- 記事タイプとストーリーパターン（なぜそれを選んだか1行で）
- タイトル案（結論・主張を含む副題つき、2〜3案）
- 見出しレベルのアウトライン（各見出しに「ここで何を書くか」「入れる具体例」を1行添える）
- 埋めるべき具体例リスト（プロンプト全文／失敗例／数値の置き場所）
ここで 必ずユーザーの承認・修正を受けてから 本文に進みます。骨格が固まる前に本文を書くと、後戻りが大きくなるためです。
ステップ4 — 骨格に沿って本文ドラフトを書く
承認されたアウトラインに沿って本文を書きます。執筆中は次を守ります。
- 見出しだけ読んで要点が伝わること（見出し＝主張の断言形が望ましい）
- 各主要セクションに 具体例（プロンプト全文・失敗シナリオ・数値） を最低1つ
- セクション内は「主張1文 → 観察 → 具体例 → 読者への含意」のマイクロ構造（詳細は
references/story-patterns.md）
- 締めは 番号付き Lessons か 価値・感情 のどちらかで閉じる
Zenn 記事として出力する場合は frontmatter（title / emoji / type / topics / published）を付けます。本文の声・主張を強めたいときは opinionated-tech-writing の原則を併用します。
執筆後のチェックリスト
ドラフトを書き終えたら確認します。これは「型に沿えているか」の最終確認です。
リソース
references/article-types.md — タイプ A/B/C の詳細アウトラインと記事タイプ早見表references/story-patterns.md — ストーリーパターン5種の詳細、セクション内マイクロ構造、具体性の置き方assets/outline-templates.md — コピペ用アウトライン雛形（A/B/C）
補足
このスキルは骨格を整えるための補助輪です。型は出発点であって檻ではありません。題材が型に収まらないときは、近いタイプを基準にしつつセクションを足し引きして構いません。大事なのは「読者が読み終えて何を持ち帰るか」を最初に決め、その一点に向けて全セクションを並べることです。
