technical-tutorials

技術チュートリアル

このスキルは、実際に動作するステップ形式のチュートリアルを作成するのに役立ちます。前提条件の扱い、段階的な複雑さ、トラブルシューティングのセクション、そして「動いた！」という満足感のある瞬間を作る方法を扱います。

---

始める前に

まず、対象読者のコンテキストを読み込みます。 .agents/developer-audience-context.md を読んで、以下を把握してください。

• 開発者のスキルレベル（初心者、中級者、上級者）
• 技術スタックへの習熟度（どの程度の知識を前提にできるか）
• 環境（macOS、Linux、Windows、クラウド）
• 学習する理由（仕事、サイドプロジェクト、興味）

コンテキストファイルが存在しない場合は、まず developer-audience-context スキルを実行してください。

---

チュートリアルの種類

種類	長さ	目的	例
クイックスタート	5-10 分	できるだけ早く最初の成功を体験する	「初めての API 呼び出しを行う」
チュートリアル	20-45 分	概念を深く学ぶ	「Node.js で REST API を構築する」
ワークショップ	1-3 時間	包括的なプロジェクト	「フルスタックアプリを構築する」
コードウォークスルー	さまざま	既存のコードを説明する	「SDK アーキテクチャを理解する」

---

チュートリアルの構成

優れたチュートリアルの構造

1. Title & Meta
   - What you'll build
   - Time estimate
   - Prerequisites

2. Overview
   - What you'll learn
   - Final result preview

3. Prerequisites Check
   - Environment setup
   - Verification commands

4. The Build (Progressive Steps)
   - Step 1: Simplest foundation
   - Step 2: Add one concept
   - Step 3: Add complexity
   - [Checkpoint: "It works!" moment]
   - Step 4: Continue building
   - ...
   - [Final checkpoint]

5. What You Built
   - Recap
   - Complete code

6. Troubleshooting
   - Common errors
   - Debugging tips

7. Next Steps
   - Where to go from here
   - Related tutorials

---

前提条件の扱い

前提条件のセクション

具体的に説明します。必要なものを開発者に推測させないでください。

## Prerequisites

Before starting, make sure you have:

| Requirement | Version | Check Command |
|-------------|---------|---------------|
| Node.js | 18+ | `node --version` |
| npm | 9+ | `npm --version` |
| Git | Any | `git --version` |

You should also be comfortable with:
- Basic JavaScript (variables, functions, async/await)
- Command line basics (cd, mkdir, running commands)
- REST API concepts (HTTP methods, JSON)

**New to any of these?** Check out [link to prerequisite tutorial].

環境設定のセクション

誰でも確実にセットアップできるようにします。

## Setting Up Your Environment

### 1. Create Project Directory

\`\`\`bash
mkdir my-awesome-project
cd my-awesome-project
\`\`\`

### 2. Initialize the Project

\`\`\`bash
npm init -y
\`\`\`

You should see output like:
\`\`\`json
{
  "name": "my-awesome-project",
  "version": "1.0.0",
  ...
}
\`\`\`

### 3. Install Dependencies

\`\`\`bash
npm install express dotenv
\`\`\`

### 4. Verify Installation

\`\`\`bash
node -e "require('express'); console.log('Express installed!')"
\`\`\`

Expected output: `Express installed!`

---

段階的な複雑さ

レイヤーを重ねるアプローチ

理解しやすいレイヤーを積み重ねます。

レイヤー	内容	例
1. 骨組み	実行できる最小限のコード	「Hello World」サーバー
2. コア機能	主な機能	API エンドポイントを 1 つ追加
3. 実データ	ハードコードされた値を置き換える	データベースに接続
4. エラー処理	本番環境に対応したパターン	try/catch と検証を追加
5. 仕上げ	あると便利なもの	ロギング、設定、テスト

完璧さではなく進捗を示す

悪いアプローチ（圧倒される例）：

// Here's the complete file with everything
const express = require('express');
const { Pool } = require('pg');
const helmet = require('helmet');
const rateLimit = require('express-rate-limit');
const winston = require('winston');
// ... 200 more lines

良いアプローチ（段階的）：

ステップ 1：基本的なサーバー

const express = require('express');
const app = express();

app.get('/', (req, res) => {
  res.send('Hello World!');
});

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

ステップ 2：最初のルートを追加

// Add this below your existing route
app.get('/api/users', (req, res) => {
  res.json([{ id: 1, name: 'Jane' }]);
});

---

コピーしてすぐ使えるコード

コピー＆ペーストのチェックリスト

すべてのコードブロックで、以下のテストに合格する必要があります。

テスト	確認方法
単独で実行できる	新しいファイルにコピーして実行し、動作する
インポートが含まれている	すべての require／import 文が記載されている
未定義の変数がない	他のステップのコードを示さずに参照していない
環境に依存しない	Mac／Linux／Windows で動作する
コメントが理由を説明している	何をするか（コードを見ればわかる）ではなく、なぜそうするか

コードブロックのパターン

ファイルのコンテキストは重要です。

// server.js - Add this to your existing file
const rateLimit = require('express-rate-limit');

// Add this BEFORE your routes
const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100 // limit each IP to 100 requests per window
});

app.use(limiter);

ファイル構成を示します。

my-project/
├── src/
│   ├── index.js      ← You're editing this
│   ├── routes/
│   │   └── users.js
│   └── db/
│       └── connection.js
├── package.json
└── .env

前後のコードを含めて変更箇所を示します。

// src/index.js
const express = require('express');
const app = express();

// ✅ ADD THIS: Import your new route
const userRoutes = require('./routes/users');

// ✅ ADD THIS: Use the route
app.use('/api/users', userRoutes);

app.listen(3000);

---

「動いた！」という瞬間

チェックポイントでモチベーションを高める

3〜5 ステップごとに、開発者が達成感を得られるようにします。

## Checkpoint: Test Your API

Let's make sure everything works before continuing.

**Start your server:**
\`\`\`bash
node server.js
\`\`\`

**In a new terminal, test the endpoint:**
\`\`\`bash
curl http://localhost:3000/api/users
\`\`\`

**You should see:**
\`\`\`json
[{"id": 1, "name": "Jane"}]
\`\`\`

🎉 **It works!** Your API is returning data.

If you don't see this output, check the [Troubleshooting](#troubleshooting) section.

視覚的な確認

可能であれば、成功時の状態を示します。

出力の種類	表示方法
ターミナル出力	期待されるテキストを含むコードブロック
ブラウザーの結果	スクリーンショットまたは説明
API レスポンス	整形済みの JSON
ログ	ログ出力を含むコードブロック

---

トラブルシューティングのセクション

よくあるエラーのテンプレート

## Troubleshooting

### "Error: Cannot find module 'express'"

**Cause:** Dependencies weren't installed.

**Fix:**
\`\`\`bash
npm install
\`\`\`

---

### "EADDRINUSE: address already in use :::3000"

**Cause:** Another process is using port 3000.

**Fix (macOS/Linux):**
\`\`\`bash
# Find the process
lsof -i :3000

# Kill it (replace PID with actual number)
kill -9 PID
\`\`\`

**Or use a different port:**
\`\`\`javascript
app.listen(process.env.PORT || 3001);
\`\`\`

---

### "SyntaxError: Unexpected token"

**Cause:** Likely a typo or missing bracket.

**Debug steps:**
1. Check the line number in the error
2. Look for missing `,`, `}`, or `)`
3. Verify all strings are closed with matching quotes

エラーの事前防止

よくある落とし穴の前に警告を追加します。

⚠️ **Windows users:** Use `set` instead of `export`:
\`\`\`bash
# macOS/Linux
export API_KEY=your_key

# Windows Command Prompt
set API_KEY=your_key

# Windows PowerShell
$env:API_KEY="your_key"
\`\`\`

---

チュートリアルのテンプレート

クイックスタートのテンプレート（5-10 分）

# [Product] Quickstart: [What You'll Do] in 5 Minutes

Get [specific outcome] in under 5 minutes.

## Prerequisites

- [Requirement 1]
- [Requirement 2]

## Step 1: Install

\`\`\`bash
npm install your-package
\`\`\`

## Step 2: Configure

Create a `.env` file:
\`\`\`
API_KEY=your_key_here
\`\`\`

## Step 3: Write Code

Create `index.js`:
\`\`\`javascript
// Complete, working code
\`\`\`

## Step 4: Run It

\`\`\`bash
node index.js
\`\`\`

Expected output:
\`\`\`
[Output here]
\`\`\`

## 🎉 You Did It!

You just [accomplished thing].

**Next steps:**
- [Link to full tutorial]
- [Link to API docs]
- [Link to examples repo]

完全なチュートリアルのテンプレート（20-45 分）

# Build a [Thing] with [Technology]

Learn how to [outcome] by building [specific project].

| | |
|---|---|
| **Time** | 30 minutes |
| **Level** | Intermediate |
| **Prerequisites** | Node.js 18+, basic JavaScript |

## What You'll Build

[Screenshot or diagram of final result]

By the end, you'll have:
- ✅ [Capability 1]
- ✅ [Capability 2]
- ✅ [Capability 3]

## Prerequisites

### Required Software

| Tool | Version | Verify |
|------|---------|--------|
| Node.js | 18+ | `node -v` |

### Required Knowledge

- [Concept 1] — [link to learn]
- [Concept 2] — [link to learn]

## Step 1: Project Setup

[Setup instructions with verification]

**Checkpoint:** You should see `[expected output]`.

## Step 2: [First Feature]

[Instructions]

**Checkpoint:** Test with `[command]`.

## Step 3: [Second Feature]

[Instructions]

## Step 4: [Third Feature]

[Instructions]

**Checkpoint:** Your app should now [do thing].

## Complete Code

Here's everything together:

\`\`\`javascript
// Full final code
\`\`\`

## Troubleshooting

### [Common Error 1]
[Solution]

### [Common Error 2]
[Solution]

## What You Learned

- [Key concept 1]
- [Key concept 2]
- [Key concept 3]

## Next Steps

- **Go deeper:** [Link to advanced tutorial]
- **Explore:** [Link to related feature]
- **Get help:** [Link to Discord/community]

---

品質チェックリスト

公開する前に、以下を確認します。

コードの品質

• すべてのコードブロックが変更なしで実行できる
• すべてのインポート／require が含まれている
• 期待される出力が示されている
• エラー処理が含まれている
• 環境変数に .env パターンを使用している

構成の品質

• 前提条件が明確になっている
• 所要時間の見積もりが正確である（実際に試すこと！）
• 3〜5 ステップごとにチェックポイントがある
• 最終的な完全版のコードが提示されている
• トラブルシューティングで起こりそうなエラーを扱っている

アクセシビリティ

• Mac、Linux、Windows で動作する
• bash/zsh/PowerShell でコマンドが動作する
• ファイルパスで正しい区切り文字を使用する
• インストール済みツールを前提としない

---

ツール

ツール	使用例
Octolens	開発者がよく直面する質問やエラーを見つけます。トラブルシューティングのコンテンツを探すため、Stack Overflow と GitHub のイシューを監視します。
Replit/CodeSandbox	実行可能なサンプルを埋め込みます
Carbon/Ray.so	見栄えのよいコードのスクリーンショットを作成します
Excalidraw	アーキテクチャ図を作成します
Terminalizer	ターミナルのセッションを記録します
Loom	手軽な動画補足を作成します

---

関連スキル

• developer-audience-context — スキルレベルと環境を把握します
• devrel-content — 技術文書作成の一般原則
• developer-onboarding — 最初に成功するまでの時間を短縮します
• developer-seo — 検索からチュートリアルを見つけてもらいます