tech-blog-writing

name	tech-blog-writing
description	テックブログのネタ発見、一次経験の整理、媒体・記事タイプ選定、構成設計、公開前の根拠確認を一貫して支援する。Zenn・Qiita・noteの記事案または既存原稿を、経験・判断・検証の来歴が読者へ伝わる状態にする。

tech-blog-writing

テックブログを「整った文章」ではなく、実務経験を再利用可能な技術知識へ変換するためのスキル。

文章生成そのものより、次を重視する。

• 誰のどの課題を扱うか
• 何を実際に経験・観測したか
• どの判断が、どの証拠によって変わったか
• どの条件まで主張できるか
• 何を書かないか

トリガー

• テックブログのネタを考える
• 作業ログ、Issue、PR、障害対応、技術選定から記事候補を抽出する
• 記事の構成や書き方を決める
• /check-tech-blog <記事パスまたは記事案> で確認する
• Zenn・Qiita・note向けの記事が、一次経験と根拠を備えているかレビューする

正本と関連ルール

最初に次を読む。

1. AGENTS.md — 全媒体共通の規約
2. docs/content-channel-strategy.md — 媒体役割、書き分け、多媒体展開の正本
3. 対象媒体の構成・運用ルール
   • Zenn: docs/article-guides/zenn-structure-best-practices.md と articles/README.md
   • note: articles_note/guides/note-structure-best-practices.md、articles_note/checklists/note-article-quality-checklist.md、articles_note/README.md
   • Qiita: Qiita/README.md など既存の媒体固有ルール

媒体選定後に構成案を作る場合は、対象媒体の構成ガイドを先に読み、その判断基準を構成案へ反映する。ガイドは固定テンプレートとして機械適用せず、記事の目的・読者・検索意図・一次経験を優先する。

本スキルは媒体別レビューを置き換えない。

• Zennレビュー: article-reviewer / article-review-apply
• noteレビュー: note-article-review
• AI特有表現の検出: article-humanizer-ja
• 公開操作: /publish-zenn、/publish-qiita など既存フロー

基本原則

1. AIは編集者であり、経験の生成者ではない

AIへ任せてよいもの:

• 作業ログからの論点抽出
• 不足情報を明らかにする質問
• 構成案、見出し案、タイトル案
• 冗長さ、重複、表現のレビュー
• 公式情報と本文の照合補助

AIへ任せてはいけないもの:

• 経験していない失敗・成果・感情の生成
• 未実行コードの成功断定
• 観測していない数値や効果の生成
• 技術判断と事実確認の最終責任

不足する一次情報は補完せず、著者確認が必要 として返す。

2. 身体性は文体ではなく知識の来歴で示す

「私は思った」だけでは一次経験として弱い。可能な範囲で次の因果を残す。

当初の期待
→ 実行したこと
→ 観測した事実
→ 解釈・仮説
→ 判断の変更
→ 次回の行動

最低限、次のどれかを含める。

• 実際に発生した問題とその条件
• 試した案と採用・不採用理由
• ログ、テスト、メトリクス、diff、Issue、PRなどの証拠
• 導入前後で変わった判断または運用

3. 1記事1主張を基本にする

記事の中心主張を1文で説明できる状態にする。補助メッセージは原則3つまで。

関連していても中心主張を強めない内容は、次のいずれかへ分ける。

• 削除
• 別記事
• 補足
• 今後の課題

AIが追加した一般論を残すこと自体を品質とみなさない。

4. 主張と根拠を対応させる

強い主張ほど強い根拠を要求する。

主張	必要な根拠の例
手順が動く	実行環境、バージョン、実行結果
品質が上がった	比較条件、評価軸、観測値または具体例
AがBより良い	対象タスク、制約、比較基準、例外
一般に推奨できる	公式情報、複数事例、適用条件
自分のケースで有効	実施条件、観測結果、未検証範囲

事実、推測、意見、経験を混同しない。

5. 適用範囲を明示する

防御的な言い訳ではなく、主張の境界を示す。

• 執筆・検証時点
• OS、ランタイム、ライブラリ、モデルなどの環境
• 対象タスク・チーム・規模
• 未検証条件
• 残った問題

6. 文章完成度と公開安全性を分ける

文章、図、網羅性は後から改善できる。次は公開前に満たす。

• 技術的正確性
• コード・手順の再現確認
• 機密情報、APIキー、個人情報の除外
• 引用、ライセンス、出典の確認
• 読者へ重大な損害を与えうる断定の回避

対応する記事タイプ

記事案を次のいずれかに分類する。混合する場合も主タイプを1つ決める。

タイプ	中心となる問い	基本構成
学習ログ	何を理解し直したか	前提 → 誤解 → 検証 → 学び
トラブルシュート	何が起き、どう切り分けたか	症状 → 環境 → 仮説 → 試行 → 原因 → 対策
設計・意思決定	なぜその案を選んだか	課題 → 制約 → 選択肢 → 評価軸 → 判断 → 残課題
教訓・振り返り	何を次から変えるか	期待 → 出来事 → 転機 → 教訓 → 次の行動
手順・ガイド	読者が何を再現できるか	対象 → 前提 → 手順 → 確認 → 失敗時対応
概念解説	何と何を区別すべきか	問題提起 → 定義 → 比較 → 具体例 → 適用判断
比較検討	どの条件で何を選ぶか	要件 → 候補 → 評価軸 → 検証 → 結論

ワークフロー

Mode A: 記事ネタを確認する

入力例:

• 作業ログ
• Issue / PR / ADR
• 障害対応メモ
• 技術選定の比較
• 短い記事案

A-1. Experience Recordを抽出する

次を、入力に存在する範囲で整理する。

## 作業
何をしようとしたか

## 背景・読者課題
なぜ必要だったか。誰が同じ問題を持つか

## 制約
環境、期限、コスト、既存設計、チーム条件

## 当初の想定
最初は何が正しいと思っていたか

## 観測
実際に何が起きたか

## 試行と転機
何を試し、何によって判断が変わったか

## 最終判断
何を選び、なぜ選んだか

## 証拠
ログ、テスト、数値、diff、Issue、PR、公式情報

## 未解決
未検証条件、残った課題

空欄を推測で埋めない。

A-2. ネタ判定を行う

次の3段階で返す。

• READY: 中心主張、一次経験、読者価値、根拠が揃っている
• NEEDS_INPUT: 記事価値はあるが、著者の経験・証拠・条件が不足している
• PARK: 現時点では一般論または範囲が広すぎる。作業や検証を先に行う

判定観点:

• 読者の具体的な問題があるか
• 書き手に一次経験または独自検証があるか
• 期待と結果の差、または判断の変化があるか
• 根拠を提示できるか
• 1記事へ切り出せる大きさか
• 既存記事と検索意図が重複しないか
• 媒体役割に適合するか

A-3. 媒体と記事タイプを提案する

docs/content-channel-strategy.md を正として、推奨媒体を1つに絞る。

• note: 一次体験、背景、思想、マネジメント、判断の変化
• Zenn: 技術設計、実装、アーキテクチャ、体系化
• Qiita: 短いTips、トラブルシュート、検索起点の再現手順

多媒体展開は、同一本文の転載ではなく、別の読者意図へ再構成する場合だけ提案する。

媒体を決めた後に構成案を出す場合は、「正本と関連ルール」で指定した媒体別構成ガイドを必ず読み直す。

Mode B: 既存記事を確認する

対象パス:

• articles/<slug>.md
• Qiita/public/<slug>.md
• articles_note/new/<slug>.md
• articles_note/drafts/<slug>.md（読み取り専用であることを明記）
• articles_note/published/<slug>.md（公開済みであることを明記）

B-1. 中心主張を抽出する

本文から次を1文ずつ抽出する。

• 想定読者
• 読者の問題
• 中心主張
• 読後に残す理解・判断・行動

抽出できない場合は欠落として指摘する。ただし、すべての記事に明示的なCTAや行動を要求しない。

B-2. 6ゲートで確認する

1. Reader Gate: 誰の何を解決する記事か
2. Experience Gate: 実際の経験、観測、判断変化があるか
3. Evidence Gate: 主張と根拠が対応しているか
4. Scope Gate: 適用条件と未検証範囲が明確か
5. Subtraction Gate: 一般論、重複、別テーマを削れるか
6. Channel Gate: 媒体役割、形式、読者意図に適合するか

各ゲートを PASS / WARN / FAIL で判定する。指摘ゼロを許容し、問題を捏造しない。

B-3. 既存レビューへ引き渡す

本スキルは記事の上流品質を確認する。必要に応じて次へ接続する。

• 文体・AI特有表現: /humanize-review <path>
• Zennの詳細レビュー: /review-article <slug>
• noteの詳細レビュー: /review-note-article <state>/<slug>
• 多視点検証: /multi-review <path> <観点>

出力形式

記事ネタモード

# Tech Blog Idea Check

## 判定
READY | NEEDS_INPUT | PARK

## 中心主張候補
1文

## 一次経験・独自性
- 確認できたもの
- 不足しているもの

## 推奨
- 媒体:
- 記事タイプ:
- 想定読者:

## 根拠マップ
| 主張候補 | 根拠 | 状態 |

## 構成案
必要最小限の見出し

## 著者確認が必要
推測せず質問または不足事項を列挙

既存記事モード

# Tech Blog Check

## 総合判定
PASS | NEEDS_REVISION | BLOCKED

## 記事の核
- 想定読者:
- 読者課題:
- 中心主張:
- 読後価値:

## Gate Results
| Gate | 判定 | 根拠 |

## 優先修正
最大5件。重要度順

## 削れる内容
一般論、重複、別記事候補

## 著者確認が必要
経験、数値、判断理由などAIが補完できない項目

## 次のレビュー
既存コマンドへの接続提案

ガードレール

• レビューのみの依頼では記事本文を変更しない
• 著者の経験、失敗、成果、感情を捏造しない
• 未検証コードを動作済みと扱わない
• 出典を確認できない外部主張を断定しない
• 一般論を無理に一次経験へ見せかけない
• 記事の中心主張を、著者確認なく別の主張へ変えない
• 公開、マージ、published / ignorePublish の切替を行わない
• articles_note/drafts/ を編集しない

参考

• AGENTS.md
• docs/content-channel-strategy.md
• docs/article-guides/zenn-structure-best-practices.md
• articles_note/guides/note-structure-best-practices.md
• articles_note/checklists/note-article-quality-checklist.md
• .claude/skills/article-humanizer-ja/SKILL.md
• .claude/skills/article-review-apply/SKILL.md
• .claude/skills/note-article-review/SKILL.md
• Forkwellイベント「おい、テックブログを書け」: https://jobs.forkwell.com/events/c8fat8q8c