technical-writing

テクニカルライティングスキル

概要

開発中の機能について、技術ブログ記事を作成します。このスキルでは、コードベースを分析して実装を理解したうえで、技術的な詳細と読みやすさのバランスを取り、明快で興味を引くコンテンツを構成します。また、AI が書いたような表現を避けます。

プロセス

フェーズ 1：調査と計画

1.1 ライティングガイドを読み込む（必須 — 最初に読み込む）

ほかの作業に入る前に、次のガイドを読み込みます。

1. ライティングルール（WRITING_ANTI_PATTERNS_PATH 環境変数で指定されたファイル、またはフォールバック先の references/anti-patterns.md）— 避けるべき、AI が書いたように聞こえる単語、フレーズ、パターンを網羅した一覧です。これは基盤となるガイドで、どのような表現を避けるべきかを示します。

2. ライティングスタイルガイド（WRITING_STYLE_GUIDE_PATH 環境変数で指定されたファイル、またはフォールバック先の references/style-guide.md）— 個人の文体、トーン、構成、特徴的な表現をまとめたガイドです。これは文体の指針となり、どのような表現を使うべきかを示します。

優先ルール：ガイド同士が矛盾する場合は、アンチパターンを優先します。スタイル上の選択よりも、AI らしいパターンを避けることを常に優先します。

1.2 WordPress のタクソノミーを取得する（設定されている場合）

WORDPRESS_URL、WORDPRESS_USERNAME、WORDPRESS_APP_PASSWORD の環境変数が設定されている場合は、記事を書く前に利用可能なカテゴリーとタグを取得し、フロントマターでは既存のタクソノミーを使用します。

curl -s -u "$WORDPRESS_USERNAME:$WORDPRESS_APP_PASSWORD" \
  "$WORDPRESS_URL/wp-json/wp/v2/categories?per_page=100" | python3 -c "import sys,json; [print(c['name']) for c in json.load(sys.stdin)]"

curl -s -u "$WORDPRESS_USERNAME:$WORDPRESS_APP_PASSWORD" \
  "$WORDPRESS_URL/wp-json/wp/v2/tags?per_page=100" | python3 -c "import sys,json; [print(t['name']) for t in json.load(sys.stdin)]"

フロントマターで category と tags を選ぶ際に、これらを使用します。既存の値を優先してください。WordPress の環境変数が設定されていない場合は、この手順を省略します。

1.3 実装内容を把握する

コードベースを調査し、機能の内容を把握します。

• どの機能や変更について書きたいかを確認します
• 関連する場合は、git を使って最近のコミットを確認します（git リポジトリでない場合は省略します）：git log --oneline -10
• 関連するコードファイルを読み、実装を把握します
• 重要な技術的判断、アーキテクチャ、興味深い詳細を特定します
• 解決した課題や巧みな解決策を記録します

1.4 構成を計画する

記事で取り上げる内容を計画します。以下はガイドとして使用し、厳格なテンプレートとして扱わないでください。

• 導入：開発した内容に関連する、興味を引くきっかけや背景から始めます
• 概要：機能について 2〜3 文で簡潔に説明します
• 課題／価値：なぜ重要なのか、どのような課題を解決するのかを説明します
• 技術的な詳細：コードスニペットを使って仕組みを説明します
  • 重要な実装の詳細
  • 興味深い技術的判断
  • 使用したアーキテクチャやデザインパターン
• 課題：難しかった点とその解決方法を説明します（該当する場合）
• 今後の予定：次のステップや関連機能を説明します（該当する場合）
• 技術スタック：使用した技術を紹介します（本文に織り込むか、一覧にできます）

実際の見出し、構成、流れは定型的ではなく、記事の内容に合わせて自然なものにします。

フェーズ 2：執筆

2.1 下書きの作成

フェーズ 1 で読み込んだ両方のガイドを適用してブログ記事を作成します。下書きの作成後、アンチパターンガイドに照らして記事を再確認し、違反があれば修正してから保存します。

コードスニペット：

• スニペットは短く保ちます（5～15 行）。

目標の長さ：内容の複雑さに合わせます。特に指定がなければ短めにします。

• シンプルなアイデア、告知、または単一の概念：400～600 語
• 中程度の技術的な解説：600～900 語
• 詳細なアーキテクチャの解説、または複数パートから成る説明：900～1200 語

短めにすることを心がけます。500 語で伝えられる内容を、800 語に引き延ばさないでください。冗長な部分を削り、内容の薄いセクションをまとめ、要点を伝えたら終わりにします。

2.2 下書きの保存

完成したブログ記事を下書きディレクトリに保存します（存在しない場合はフォルダーを作成します）。

保存先を確認するには、次を実行します：echo $WRITING_DRAFTS_PATH

• 出力が空でなければ、その場所に保存します
• 空の場合は、現在のプロジェクト内の .drafts/ に保存します

ファイル名の規則：

• 形式：YYYY-MM-DD-slug.md
• スラッグは短く、覚えやすく、入力しやすいものにします。単語は 2 つまでです
• 必ずしもタイトルと同じでなくて構いません。記事の中心となる概念を表します
• 「ドメイン名の後に何を入力するか」を考えます
• 例：2025-12-29-ralph.md（記事：「How I Got Ralph to Ship Overnight」）、2026-01-10-listen.md（記事：「Giving my blog a voice」）、2025-11-15-choosing-open.md（記事：「WordPress Almost Didn't Happen」—オープンソースを選んだことについて）

フロントマター（必須）：

すべての下書きは、title と url を含む YAML フロントマターで始めてください：

---
title: How I got Ralph to ship overnight
url: /ralph
category: Development
tags:
  - AI
  - Shipping
---

• title — 記事のタイトル（本文で H1 として繰り返さないでください）。タイトルは短く（3～7 語）、印象的で、読者の好奇心をかき立てるものにします。記事の全容を説明せず、内容をほのめかしてください。説明文ではなく、新聞の見出しを意識します。
  • 良い例：「Giving my blog a voice」、「WordPress Almost Didn't Happen」、「Planning Out Loud」
  • 悪い例：「I built a skill that writes blog posts from my codebase」（長すぎて、すべてを説明しています）
• url — ファイル名のスラッグに合わせたパーマリンクのパス（例：/ralph、/listen、/choosing-open）
• category — WordPress のカテゴリー（該当するものがあれば、フェーズ 1.2 で確認した既存のものを使用します）
• tags — WordPress のタグ（フェーズ 1.2 で確認した既存のタグを優先します）

フェーズ 3：公開（任意）

3.1 WordPress への公開

ユーザーが WordPress への公開を希望する場合は、設定と公開手順の詳細を確認するため、WordPress Publishing Guide（references/wordpress-publishing.md）を読み込みます。

ガイドには以下の内容が含まれます：

• 環境設定と認証情報
• Python の依存関係のインストール
• 公開コマンドとワークフロー
• 更新の追跡（投稿の重複を防止）
• よくある問題のトラブルシューティング

概要：

• 初回：新しい WordPress の下書きを作成します
• 2 回目以降：既存の下書きを更新します（重複は作成しません）
• 常に下書きとして保存します（自動公開はしません）
• 投稿 URL と編集 URL を返します

出力形式

ブログ記事を作成して保存した後、以下を提示します：

1. 保存先：記事を保存したパス
2. 記事タイトル：最終的に使用したタイトル
3. 参照した主なファイル：行番号を添えた、記事内で言及したファイルのリスト
4. 語数：おおよその長さ

やり取りの例

ユーザー：「音声プランニング機能について書くのを手伝って」

回答：

Let me investigate the voice planning implementation to write about it.

[Phase 1: Loads anti-patterns + style guide, fetches WP taxonomy, reads code]

[Phase 2: Creates and saves blog post applying both guides]

Blog post saved to: .drafts/2025-12-29-planning-aloud.md

Title: "Planning Out Loud"

Key Files Referenced:
- src/components/voice-session.tsx:78 (voice session initialization)
- src/app/api/webhook/route.ts:40 (webhook signature validation)
- src/lib/claude.ts:88 (Claude tool calling)

Word Count: ~550 words

環境変数

Claude Code の設定（~/.claude/settings.json）の env キーの下で設定します。

{
  "env": {
    "WRITING_STYLE_GUIDE_PATH": "/path/to/style-guide.md",
    "WRITING_ANTI_PATTERNS_PATH": "/path/to/anti-patterns.md",
    "WRITING_DRAFTS_PATH": "/path/to/drafts",
    "WORDPRESS_URL": "https://yourblog.com",
    "WORDPRESS_USERNAME": "your_username",
    "WORDPRESS_APP_PASSWORD": "xxxx xxxx xxxx xxxx",
    "WRITING_TITLE_CASE_STYLE": "title",
    "WRITING_HEADING_CASE_STYLE": "sentence"
  }
}

変数	必須	説明
WRITING_STYLE_GUIDE_PATH	いいえ	共有の文体ガイドへのパスです。フェーズ 1.1 で読み込まれます
WRITING_ANTI_PATTERNS_PATH	いいえ	共有のアンチパターンへのパスです。references/anti-patterns.md を上書きします
WRITING_DRAFTS_PATH	いいえ	下書きの保存先です。指定がない場合は、現在のプロジェクトの .drafts/ が使用されます
WORDPRESS_URL	公開する場合	WordPress サイトの URL です（https:// を含めてください）
WORDPRESS_USERNAME	公開する場合	WordPress アカウントのユーザー名です
WORDPRESS_APP_PASSWORD	公開する場合	アプリケーションパスワードです（通常のパスワードではありません）
WRITING_TITLE_CASE_STYLE	いいえ	"sentence"（デフォルト）または "title"
WRITING_HEADING_CASE_STYLE	いいえ	"sentence"（デフォルト）または "title"

最良の結果を得るためのヒント

1. 範囲を具体的に指定する：「Webhook について書いて」よりも、「Webhook のセキュリティ実装について書いて」のほうが適切です
2. 対象読者を伝える：「Next.js に詳しい開発者向け」と「技術に詳しくない読者向け」のように指定します
3. 希望する長さを指定する：「500 語程度の簡潔な更新」と「詳細な掘り下げ」のように指定します
4. 背景情報を共有する：「これはシリーズの第 2 回です」や「このプロジェクトについての初めての記事です」と伝えます
5. 修正を依頼する：下書きの後で、セクションの拡充、説明の簡略化、トーンの調整などを依頼します

応用：シリーズ記事

複数回にわたるシリーズの場合：

• 「[topic] についての 3 回シリーズの構成を考えるのを手伝って」と依頼します
• 各記事は前の記事を踏まえた内容にします
• 「これまで」と「次回予告」のセクションを含めます
• 記事全体で一貫した構成を保ちます