article-writer

記事ライター

技術記事と、関連プロジェクトおよび多言語対応を作成します。

クイックスタート

1. 著者を決定します（タスクの指定、またはデータベースのデフォルト著者を使用）
2. フォルダー構成を作成します（code/ フォルダーを含む）
3. データベースから著者プロフィールを読み込みます
4. 設定を読み込みます（article_limits.max_words を含む）
5. 次のフェーズに従います：初期化 → 計画 → 調査 → 下書き → 関連プロジェクト → 統合 → レビュー → 簡潔化 → 翻訳 → 最終化

ワークフローの概要

Plan → Research → Draft (initial) → Create Companion Project → Update Draft → Review → Condense → Translate → Finalize
                         ↑                              ↓               ↓
                         └──────── Iterate ─────────────┘               │
                                                                        ↓
                                                            (if over max_words)

フォルダー構成

content/articles/YYYY_MM_DD_slug/
├── 00_context/              # author_profile.json
├── 01_planning/             # classification.md, outline.md
├── 02_research/
│   ├── sources.json         # All researched sources
│   └── research_notes.md
├── 03_drafts/
│   ├── draft_v1.{lang}.md   # Initial draft
│   └── draft_v2.{lang}.md   # After companion project integration
├── 04_review/               # checklists
├── 05_assets/images/
├── code/                    # COMPANION PROJECT
│   ├── README.md            # How to run the companion project
│   ├── src/                 # Companion project source code/files
│   └── tests/               # Tests (if applicable)
├── {slug}.{primary_lang}.md # Primary article
└── {slug}.{other_lang}.md   # Translations

フェーズ

フェーズ 0：初期化

• 著者を取得し、スラッグを生成して、フォルダーを作成します
• 関連プロジェクト用に code/ ディレクトリーを作成します
• 著者プロフィールを 00_context/ にコピーします
• 設定から article_limits.max_words を読み込みます

フェーズ 1：計画

• 記事の種類を分類します
• アウトラインを作成します
• 関連プロジェクトの種類と範囲を計画します
• チェックポイント： 承認を得ます

フェーズ 2：調査（ウェブ検索）

• 公式ドキュメントを検索します
• 最近のニュースを探します（技術記事では 1 年以内）
• すべての情報源を記録します

フェーズ 3：下書き（初稿）

• 主言語で初稿を書きます
• サンプルコードを挿入する箇所にマークを付けます：``
• 03_drafts/draft_v1.{lang}.md として保存します

著者の文体を反映する

執筆時には著者プロフィールのデータをすべて使用してください：

1. 手動プロフィールデータ

   • tone.formality：1＝非常にくだけた表現、10＝非常に形式的な表現
   • tone.opinionated：1＝常に断定を避ける、10＝強い意見を述べる
   • phrases.signature：自然に使います（使いすぎないでください）
   • phrases.avoid：これらの表現は使いません
   • vocabulary.use_freely：読者がこれらを知っているものとして扱います
   • vocabulary.always_explain：初出時に説明します

2. 文体分析データ（voice_analysis が存在する場合）

   • sentence_structure.avg_length：この文の長さを目標にします
   • sentence_structure.variety：スタイル（短め／中程度／長め）を合わせます
   • communication_style：上位の特徴を語調に反映します
   • characteristic_expressions：自然に散りばめます
   • sentence_starters：これらのパターンを使います
   • signature_vocabulary：これらの単語を優先して使います

例：

次のような著者の場合：

{
  "tone": { "formality": 4, "opinionated": 7 },
  "voice_analysis": {
    "sentence_structure": { "avg_length": 14, "variety": "moderate" },
    "communication_style": [{ "trait": "enthusiasm", "percentage": 32 }],
    "characteristic_expressions": ["na prática", "o ponto é"],
    "sentence_starters": ["Então", "O interessante é"]
  }
}

次のように書きます：

• 親しみやすく、自信のある語調
• 中程度の長さの文（約 14 語）
• 熱意のある雰囲気
• 「na prática」や「o ponto é」を時折使用
• 「Então」や「O interessante é」で始まる文もいくつか使用

フェーズ 4：関連プロジェクトの作成 ⭐

このフェーズでは Skill(companion-project-creator) を使用してください

重要：関連プロジェクトは、完成しており、実行可能で、検証済みでなければなりません。

Laravel の関連プロジェクトは完全な Laravel インストールです。Node の関連プロジェクトは完全な Node プロジェクトです。

実際に実行してテストするまでは、関連プロジェクトは完成していません。

ステップ 1：設定から関連プロジェクトのデフォルト値を読み込む

まずデータベースから設定を読み込みます：

# View defaults for the companion project type
bun run "${CLAUDE_PLUGIN_ROOT}"/scripts/show.ts settings code

または、JSON を読み込んで抽出します：

// Settings are loaded from the database via show.ts or article-stats.ts
const codeDefaults = settings.companion_project_defaults.code;
// codeDefaults.scaffold_command
// codeDefaults.verification.install_command
// codeDefaults.verification.run_command
// codeDefaults.verification.test_command

ステップ 2：記事固有の上書き設定とマージする

記事タスクに companion_project フィールドがある場合、その値で設定のデフォルト値を上書きします。

ステップ 3：スキャフォールドコマンドを実行する

# From settings.companion_project_defaults.code.scaffold_command
composer create-project laravel/laravel code --prefer-dist

ステップ 4：記事固有のコードを追加する

スキャフォールドしたプロジェクトに、カスタムコードを追加します：

• モデル、コントローラー、ルート
• マイグレーション、シーダー
• テスト

一部のファイルだけで構成された不完全なプロジェクトを作成しないでください。

ステップ 5：検証する（必須）⚠️

次のコマンドを必ず実際に実行し、成功することを確認してください：

cd code

# 1. Install dependencies - MUST SUCCEED
composer install
# ✓ Check: No errors, vendor/ directory exists

# 2. Setup - MUST SUCCEED
cp .env.example .env
php artisan key:generate
touch database/database.sqlite
php artisan migrate
# ✓ Check: No errors

# 3. Run application - MUST START
php artisan serve &
# ✓ Check: "Server running on http://127.0.0.1:8000"
# Stop the server after confirming

# 4. Run tests - ALL MUST PASS
php artisan test
# ✓ Check: "Tests: X passed" with 0 failures

いずれかの手順が失敗した場合：

1. エラーメッセージを読みます
2. コードを修正します
3. ステップ 1 から検証を再実行します
4. すべての手順が成功するまで繰り返します

検証に成功するまでフェーズ 5 に進まないでください。

関連プロジェクトの種類

記事のトピック	プロジェクトの種類	作成するもの
Laravel/PHP コード	code	composer create-project を使った完全な Laravel プロジェクト
JavaScript/Node	node	npm init を使った完全な Node プロジェクト
Python	python	venv を含む完全な Python プロジェクト
DevOps/Docker	config	完全な docker-compose セットアップ
アーキテクチャ	diagram	完全な Mermaid 図
プロジェクト管理	document	完全なテンプレートと記入済みの例

検証チェックリスト

Phase 5 に進む前に：

• スキャフォールドコマンドが正常に実行された
• 記事固有のコードがすべて追加されている
• install_command が成功した（vendor/node_modules が存在する）
• run_command でアプリケーションがエラーなく起動する
• test_command で失敗なし（0 件）でテストが実行される
• README.md でセットアップ方法と使い方が説明されている

コードコンパニオンプロジェクト（Laravel）の場合

code/
├── README.md              # Setup and run instructions
├── app/
│   └── ...                # Minimal app code
├── database/
│   ├── migrations/
│   └── seeders/
├── tests/
│   └── Feature/           # Pest tests for main features
├── composer.json
└── .env.example           # SQLite by default

Laravel コンパニオンプロジェクトの標準：

• SQLite を使用する（外部 DB は不要）
• テストには Pest を使用する
• 主要機能のテストを少なくとも 2～3 件含める
• 記事を参照するコメントを追加する：// See article section: "Rate Limiting Basics"
• 依存関係は最小限に抑える
• 複雑な場合はセットアップスクリプトを含める

ドキュメントコンパニオンプロジェクトの場合

code/
├── README.md              # What the documents demonstrate
├── templates/
│   └── ...                # Reusable templates
└── examples/
    └── ...                # Filled-in examples

Phase 5：コンパニオンプロジェクトを草稿に統合する

• `` マーカーを実際のコードスニペットに置き換える
• ファイル参照を追加する：「code/app/Models/Post.php を参照してください」
• 適切なセクションに実行手順を追加する
• 03_drafts/draft_v2.{lang}.md として保存する

Phase 6：レビュー（包括的）

記事全体をレビューします：

1. 説明の流れ

   • 文章は論理的に展開していますか？
   • 概念は使用される前に導入されていますか？
   • コンパニオンプロジェクトは適切なタイミングで登場していますか？

2. コンパニオンプロジェクトとの統合

   • コードスニペットはコンパニオンプロジェクト全体と一致していますか？
   • ファイルパスは正しいですか？
   • 読者は手順に沿って進められますか？

3. 語り口の遵守

   • 著者のフォーマルさのレベルと一致していますか？
   • 決め台詞を適切に使用していますか？
   • 禁止されている表現を避けていますか？
   • 表明されている意見は著者の立場と一致していますか？
   • voice_analysis がある場合：
     • 文の長さは avg_length と一致していますか？
     • コミュニケーションスタイルの特徴が反映されていますか？
     • 特徴的な表現が使用されていますか（使いすぎていませんか）？

4. 技術的な正確性

   • コードスニペットは正しいですか？
   • コンパニオンプロジェクトは実際に動作しますか？
   • テストは成功しますか？

5. 完全性

   • アウトラインの項目はすべて網羅されていますか？
   • 出典は適切に引用されていますか？
   • コンパニオンプロジェクトはトピックを十分に実証していますか？

チェックポイント： 記事とコンパニオンプロジェクトの準備が整っていることを確認します

Phase 6b：文章を短縮する（語数制限の適用）⚠️

設定の max_words を記事が超える場合、このフェーズは必須です。

ステップ 1：語数を確認する

# Count words in article (excluding frontmatter and code blocks)
# Frontmatter: lines between first --- and second ---
# Code blocks: lines between ``` markers

# Simple word count of prose content only:
sed '/^---$/,/^---$/d; /^```/,/^```$/d' draft_v2.{lang}.md | wc -w

ステップ 2：設定から語数制限を読み込む

# Read max_words from settings
bun run "${CLAUDE_PLUGIN_ROOT}"/scripts/show.ts settings
# Or read JSON directly:
# bun run "${CLAUDE_PLUGIN_ROOT}"/scripts/show.ts settings

ステップ 3：制限を超えている場合は短縮する

語数 > max_words の場合：

1. 短縮対象を特定する（優先順位順）：

   • 同じ概念に関する冗長な説明
   • 過度に長い話のつなぎ
   • 繰り返される注意事項や免責事項
   • トピックの中心から外れた長い余談
   • 少数の例で十分な場合の過剰な例示

2. 短縮の手法（品質を維持する）：

   • 関連する段落をまとめる
   • 長い説明を簡潔な要約に置き換える
   • 冗長なリストを簡潔な箇条書きにする
   • 埋め草の単語や表現を削除する
   • 文の構造を簡潔にする

3. 重要：著者の語り口を維持する

   • 決め台詞や表現を残す
   • 同じトーン（フォーマルさのレベル）を保つ
   • 著者の意見の表し方を維持する
   • 特徴的な文の構造を保つ
   • voice profile の熱意や活気のレベルを維持する

4. 削除してはならないもの：

   • コード例やスニペット（語数制限の対象外です）
   • 重要な技術説明
   • 前提条件やセットアップ手順
   • 安全上の警告や重要な注意事項
   • コンパニオンプロジェクトへの参照

ステップ 4：短縮後のバージョンを確認する

短縮後：

• 語数が max_words 以下になっている
• 記事は自然に読める（ぎこちなくない）
• 重要なポイントがすべて維持されている
• 技術的な正確性が保たれている
• 全体を通して著者の語り口に一貫性がある
• 流れと文章構成が保たれている

ステップ 5：短縮した草稿を保存する

# Save as draft_v3 (condensed version)
# 03_drafts/draft_v3.{lang}.md

品質を損なわずに max_words 未満に短縮できない場合：

• タスク内に理由を記録する
• 達成した最終的な語数を記載する
• 人間によるレビューの対象として印を付ける

チェックポイント： 品質を維持したまま、記事が語数制限内に収まっていることを確認します

フェーズ 7：翻訳

• 他の言語版を作成します
• コードスニペットは変更しないでください
• 必要に応じてコード内のコメントを翻訳します

フェーズ 8：仕上げ

• フロントマターを付けて最終記事を作成します
• データベースを次の情報で更新します：
  • output_files
  • sources_used
  • companion_project の情報
• 付属プロジェクトの README が完成していることを確認します

付属プロジェクトを省略する場合

付属プロジェクトがまったく意味をなさない場合に限り、省略してください：

• 実践的な内容のない純粋な意見記事
• ニュース／発表の要約
• 歴史の振り返り
• 哲学的な議論

省略する場合は、タスクに次のように記録します：

{
  "companion_project": {
    "skipped": true,
    "skip_reason": "Opinion piece with no actionable code or templates"
  }
}

付属プロジェクトの README テンプレート

# Companion Project: [Topic]

Demonstrates [what this companion project shows] from the article "[Article Title]".

## Requirements

- PHP 8.2+
- Composer
- (any other requirements)

## Setup

\`\`\`bash
composer install
cp .env.example .env
php artisan key:generate
php artisan migrate --seed
\`\`\`

## Run Tests

\`\`\`bash
php artisan test
\`\`\`

## Key Files

| File | Description |
|------|-------------|
| `app/Models/Post.php` | Demonstrates eager loading |
| `tests/Feature/QueryTest.php` | Tests N+1 detection |

## Article Reference

This companion project accompanies the article:
- **Title**: [Article Title]
- **Section**: See "Implementing Eager Loading" section

付属プロジェクトのコメントのスタイル

<?php
// ===========================================
// ARTICLE: Rate Limiting in Laravel 11
// SECTION: Creating Custom Rate Limiters
// ===========================================

namespace App\Providers;

use Illuminate\Support\Facades\RateLimiter;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        // Custom rate limiter for API endpoints
        // See article section: "Dynamic Rate Limits"
        RateLimiter::for('api', function (Request $request) {
            return Limit::perMinute(60)->by($request->user()?->id ?: $request->ip());
        });
    }
}

タスクへの付属プロジェクトの記録

{
  "companion_project": {
    "type": "code",
    "path": "code/",
    "description": "Minimal Laravel app demonstrating rate limiting",
    "technologies": ["Laravel 11", "SQLite", "Pest 3"],
    "has_tests": true,
    "files": [
      "app/Providers/AppServiceProvider.php",
      "routes/api.php",
      "tests/Feature/RateLimitTest.php"
    ],
    "run_instructions": "composer install && php artisan test"
  }
}

参考資料

• references/article-types.md
• references/companion-project-templates.md
• references/checklists.md
• references/frontmatter.md
• references/research-templates.md