technical-blog-writing

belt CLI スキルをインストール： npx skills add belt-sh/cli

技術ブログ記事の執筆

inference.sh CLI を使って、開発者向けの技術ブログ記事を執筆します。

クイックスタート

inference.sh CLI（belt）が必要です。インストール手順

belt login

# Research topic depth
belt app run exa/search --input '{
  "query": "building REST API Node.js best practices 2024 tutorial"
}'

# Generate header image
belt app run infsh/html-to-image --input '{
  "html": "<div style=\"width:1200px;height:630px;background:linear-gradient(135deg,#0f172a,#1e293b);display:flex;align-items:center;padding:60px;font-family:ui-monospace,monospace;color:white\"><div><p style=\"font-size:18px;color:#38bdf8;margin:0\">// engineering blog</p><h1 style=\"font-size:48px;margin:16px 0;font-weight:800;font-family:system-ui;line-height:1.2\">How We Reduced API Latency by 90% with Edge Caching</h1><p style=\"font-size:20px;opacity:0.6;font-family:system-ui\">A deep dive into our CDN architecture</p></div></div>"
}'

記事の種類

1. チュートリアル／ハウツー

手順を追って説明します。読者が内容に沿って何かを作れるようにします。

Structure:
1. What we're building (with screenshot/demo)
2. Prerequisites
3. Step 1: Setup
4. Step 2: Core implementation
5. Step 3: ...
6. Complete code (GitHub link)
7. Next steps / extensions

ルール	理由
最初に完成形を見せる	読者が読み進める価値があるか判断できます
前提条件を明記する	対象外の読者の時間を無駄にしません
すべてのコードブロックを実行可能にする	コピーして実行できることが基準です
「方法」だけでなく「理由」も説明する	考え方を説明するチュートリアルは共有されやすくなります
エラー処理を含める	実際のコードにはエラーが発生します
完成したコードのリポジトリにリンクする	チュートリアル後の参考になります

2. 詳細解説／解説記事

概念、技術、アーキテクチャ上の判断について詳しく説明します。

Structure:
1. What is [concept] and why should you care?
2. How it works (simplified mental model)
3. How it works (detailed mechanics)
4. Real-world example
5. Trade-offs and when NOT to use it
6. Further reading

3. ポストモーテム／インシデントレポート

何が問題だったのか、その原因、修正内容を説明します。

Structure:
1. Summary (what happened, impact, duration)
2. Timeline of events
3. Root cause analysis
4. Fix implemented
5. What we're doing to prevent recurrence
6. Lessons learned

4. ベンチマーク／比較

ツール、アプローチ、アーキテクチャをデータに基づいて比較します。

Structure:
1. What we compared and why
2. Methodology (so results are reproducible)
3. Results with charts/tables
4. Analysis (what the numbers mean)
5. Recommendation (with caveats)
6. Raw data / reproducibility instructions

5. アーキテクチャ／システム設計

システムの構築方法と、その設計判断の理由を説明します。

Structure:
1. Problem we needed to solve
2. Constraints and requirements
3. Options considered
4. Architecture chosen (with diagram)
5. Trade-offs we accepted
6. Results and lessons

開発者向けの執筆ルール

文体とトーン

すること	しないこと
率直に書く：「コネクションプーリングを使います」	「使うことを検討してもよいかもしれません」
トレードオフを認める：「複雑さが増します」	自分の解決策が完璧だとうそぶく
チームの判断には「私たち」を使う	「私ひとりでアーキテクチャを設計しました」
具体的な数値を示す：「p99 を 800ms から 90ms に短縮しました」	「パフォーマンスが大幅に向上しました」
出典やベンチマークを引用する	出典のない主張をする
代替案にも言及する	自分の方法だけが唯一の方法だと装う

開発者が嫌うこと

❌ "In today's fast-paced world of technology..." (filler)
❌ "As we all know..." (if we all know, why are you writing it?)
❌ "Simply do X" (nothing is simple if you're reading a tutorial)
❌ "It's easy to..." (dismissive of reader's experience)
❌ "Obviously..." (if it's obvious, don't write it)
❌ Marketing language in technical content
❌ Burying the lede under 3 paragraphs of context

コード例

ルール	理由
すべてのコードブロックを実行可能にする	壊れた例は信頼を損ないます
完全に動作する例を示す	文脈のない断片は役に立ちません
フェンス付きコードブロックに言語識別子を含める	構文のハイライト表示に役立ちます
コードの後に出力や結果を示す	読者が理解を確認できます
現実的な変数名を使う	foo ではなく calculateTotalRevenue を使います
例にエラー処理を含める	実際のコードではエラーを処理します
依存関係のバージョンを固定する	「React」ではなく「React 18.2 で動作します」と示します

Good code block format:

```python
# What this code does (one line)
def calculate_retry_delay(attempt: int, base_delay: float = 1.0) -> float:
    """Exponential backoff with jitter."""
    delay = base_delay * (2 ** attempt)
    jitter = random.uniform(0, delay * 0.1)
    return delay + jitter

# Usage
delay = calculate_retry_delay(attempt=3)  # ~8.0-8.8 seconds

### Explanation Depth

| Audience Signal | Depth |
|----------------|-------|
| "Getting started with X" | Explain everything, assume no prior knowledge |
| "Advanced X patterns" | Skip basics, go deep on nuances |
| "X vs Y" | Assume familiarity with both, focus on differences |
| "How we built X" | Technical audience, can skip fundamentals |

**State your assumed audience level explicitly** at the start:

「この記事では、Docker と Kubernetes の基本概念を理解していることを前提としています。 コンテナを初めて使う方は、まず[入門記事]をご覧ください。」

## Blog Post Structure

### The Ideal Structure

```markdown
# Title (contains primary keyword, states outcome)

[Hero image or diagram]

**TL;DR:** [2-3 sentence summary with key takeaway]

## The Problem / Why This Matters
[Set up why the reader should care — specific, not generic]

## The Solution / How We Did It
[Core content — code, architecture, explanation]

### Step 1: [First thing]
[Explanation + code + output]

### Step 2: [Second thing]
[Explanation + code + output]

## Results
[Numbers, benchmarks, outcomes — be specific]

## Trade-offs and Limitations
[Honest about downsides — builds trust]

## Conclusion
[Key takeaway + what to do next]

## Further Reading
[3-5 relevant links]

種類別の文字数

種類	文字数	理由
クイックヒント	500～800	1 つの概念と 1 つの例
チュートリアル	1,500～3,000	手順を追うには詳しい説明が必要です
詳細解説	2,000～4,000	徹底的な解説
アーキテクチャ記事	2,000～3,500	図が説明の一部を担います
ベンチマーク	1,500～2,500	データとグラフが多くを説明します

図とビジュアル

図を使う場面

シナリオ	図の種類
リクエストの流れ	シーケンス図
システムアーキテクチャ	ボックスと矢印の図
判断ロジック	フローチャート
データモデル	ER 図
パフォーマンス比較	棒グラフ／折れ線グラフ
変更前／変更後	左右の比較

# Generate architecture diagram
belt app run infsh/html-to-image --input '{
  "html": "<div style=\"width:1200px;height:600px;background:#0f172a;display:flex;align-items:center;justify-content:center;padding:40px;font-family:system-ui;color:white\"><div style=\"display:flex;gap:40px;align-items:center\"><div style=\"background:#1e293b;border:2px solid #334155;border-radius:8px;padding:24px;text-align:center;width:160px\"><p style=\"font-size:14px;color:#94a3b8;margin:0\">Client</p><p style=\"font-size:18px;font-weight:bold;margin:8px 0 0\">React App</p></div><div style=\"color:#64748b;font-size:32px\">→</div><div style=\"background:#1e293b;border:2px solid #3b82f6;border-radius:8px;padding:24px;text-align:center;width:160px\"><p style=\"font-size:14px;color:#94a3b8;margin:0\">Edge</p><p style=\"font-size:18px;font-weight:bold;margin:8px 0 0\">CDN Cache</p></div><div style=\"color:#64748b;font-size:32px\">→</div><div style=\"background:#1e293b;border:2px solid #334155;border-radius:8px;padding:24px;text-align:center;width:160px\"><p style=\"font-size:14px;color:#94a3b8;margin:0\">API</p><p style=\"font-size:18px;font-weight:bold;margin:8px 0 0\">Node.js</p></div><div style=\"color:#64748b;font-size:32px\">→</div><div style=\"background:#1e293b;border:2px solid #334155;border-radius:8px;padding:24px;text-align:center;width:160px\"><p style=\"font-size:14px;color:#94a3b8;margin:0\">Database</p><p style=\"font-size:18px;font-weight:bold;margin:8px 0 0\">PostgreSQL</p></div></div></div>"
}'

# Generate benchmark chart
belt app run infsh/python-executor --input '{
  "code": "import matplotlib.pyplot as plt\nimport matplotlib\nmatplotlib.use(\"Agg\")\n\nfig, ax = plt.subplots(figsize=(12, 6))\nfig.patch.set_facecolor(\"#0f172a\")\nax.set_facecolor(\"#0f172a\")\n\ntools = [\"Express\", \"Fastify\", \"Hono\", \"Elysia\"]\nrps = [15000, 45000, 62000, 78000]\ncolors = [\"#64748b\", \"#64748b\", \"#3b82f6\", \"#64748b\"]\n\nax.barh(tools, rps, color=colors, height=0.5)\nfor i, v in enumerate(rps):\n    ax.text(v + 1000, i, f\"{v:,} req/s\", va=\"center\", color=\"white\", fontsize=14)\n\nax.set_xlabel(\"Requests per second\", color=\"white\", fontsize=14)\nax.set_title(\"HTTP Framework Benchmark (Hello World)\", color=\"white\", fontsize=18, fontweight=\"bold\")\nax.tick_params(colors=\"white\", labelsize=12)\nax.spines[\"top\"].set_visible(False)\nax.spines[\"right\"].set_visible(False)\nax.spines[\"bottom\"].set_color(\"#334155\")\nax.spines[\"left\"].set_color(\"#334155\")\nplt.tight_layout()\nplt.savefig(\"benchmark.png\", dpi=150, facecolor=\"#0f172a\")\nprint(\"Saved\")"
}'

配信

開発者が読む場所

プラットフォーム	形式	投稿方法
自分のブログ	記事全文	主要な掲載先 — 自分のコンテンツを自分で管理できます
Dev.to	クロスポスト（自分のブログへの正規 URL を指定）	Markdown をインポート
Hashnode	クロスポスト（正規 URL）	Markdown をインポート
Hacker News	リンクを投稿	プロジェクトは Show HN、体験談は tell HN
Reddit（r/programming、r/webdev など）	リンクまたはディスカッション	サブレディットのルールに従う
Twitter/X	スレッド形式の要約＋リンク	twitter-thread-creation スキルを参照
LinkedIn	内容を調整した記事＋リンク	linkedin-content スキルを参照

# Cross-post thread to X
belt app run x/post-create --input '{
  "text": "New blog post: How We Reduced API Latency by 90%\n\nThe short version:\n→ Moved computation to edge\n→ Aggressive cache-control headers\n→ Eliminated N+1 queries\n\np99 went from 800ms to 90ms.\n\nFull deep dive with code: [link]"
}'

よくある間違い

間違い	問題点	修正方法
TL;DR がない	忙しい開発者は要点をつかむ前に離れてしまいます	冒頭に 2～3 文の要約を置きます
コード例が動かない	信頼性がすべて損なわれます	公開前にすべてのコードブロックをテストします
バージョンが固定されていない	6 か月後にコードが動かなくなります	「Node 20、React 18.2 で動作します」と記載します
「X を簡単に実行できます」	見下した、恩着せがましい印象を与えます	「簡単に」「ただ」「容易に」を削除します
アーキテクチャ図がない	システムを説明する文章が延々と続きます	500 語の説明より図を 1 つ使います
マーケティング調の文体	開発者はすぐに読むのをやめます	率直で、技術的で、誠実な内容にします
トレードオフの説明がない	偏った宣伝のように読めます	常に欠点についても説明します
内容に入る前の導入が長すぎる	読者は離れてしまいます	2～3 段落で要点に入ります
依存関係のバージョンが固定されていない	将来の読者にとってチュートリアルが動かなくなります	バージョンを固定し、執筆日を記載します
「さらに読む」がない	行き止まりになり、背景情報も得られません	理解を深めるためのリンクを 3～5 件掲載します

関連スキル

npx skills add inference-sh/skills@seo-content-brief
npx skills add inference-sh/skills@content-repurposing
npx skills add inference-sh/skills@og-image-design

すべてのアプリを表示：belt app list