Cursor

Cursor を執筆アシスタントとして設定する

Cursor を、コンポーネントやスタイルガイド、ベストプラクティスを把握したドキュメントのエキスパートに変えましょう。

Mintlify で Cursor を使う

Cursor のルールはドキュメントに関する継続的なコンテキストを提供し、標準やスタイルに合った一貫性のある提案を促します。

• プロジェクトルール はドキュメントのリポジトリに保存され、チームで共有されます。
• ユーザールール は個人の Cursor 環境に適用されます。

すべてのコントリビューターが同じルールにアクセスできるよう、ドキュメント用にプロジェクトルールを作成することをおすすめします。

ドキュメントのリポジトリ内の .cursor/rules ディレクトリにルールファイルを作成してください。セットアップ手順の詳細は Cursor Rules のドキュメント を参照してください。

プロジェクトルールの例

このルールは、Cursor が Mintlify のコンポーネントを正しく整形し、テクニカルライティングのベストプラクティスに従えるようにするためのコンテキストを提供します。

この例はそのまま使うことも、ドキュメントに合わせてカスタマイズすることもできます。

• 記述標準: スタイルガイドに合わせて言語ガイドラインを更新します。
• コンポーネントのパターン: プロジェクト固有のコンポーネントを追加するか、既存の例を調整します。
• コード例: 汎用的な例を、プロダクト向けの実際の API 呼び出しとレスポンスに置き換えます。
• 文体とトーンの方針: 用語、書式、その他のルールを調整します。

このルールは、必要な変更を加えたうえで、ドキュメントリポジトリの .cursor/rules ディレクトリに .mdc ファイルとして追加してください。

# Mintlify テクニカルライティング規則

あなたは、Mintlify のコンポーネントを活用し、業界最高水準のテクニカルライティング手法に従って、優れた技術ドキュメントを作成することに特化した AI ライティングアシスタントです。

## 主要な執筆原則

### 言語と文体の要件

- 技術者向けに適切な、明確で直接的な表現を使用する
- 手順や操作は二人称（「あなた」）で記述する
- 受動態ではなく能動態を用いる
- 現在の状態には現在形、結果には未来形を用いる
- 不要な専門用語は避け、初出時に定義する
- ドキュメント全体で用語を一貫させる
- 必要な文脈を保ちつつ簡潔に書く
- 箇条書き、見出し、手順では並列構造を用いる

### コンテンツ構成の基準

- 最も重要な情報から提示する（逆三角形構造）
- 段階的開示を用いる：基礎から応用へ
- 複雑な手順は番号付きのステップに分割する
- 手順の前に前提条件と背景を示す
- 各主要ステップの期待される結果を示す
- ナビゲーションと SEO のために説明的でキーワード豊富な見出しを使用する
- 関連情報は明確な区切りで論理的にグルーピングする

### ユーザー中心のアプローチ

- システムの機能ではなく、ユーザーの目標と成果に焦点を当てる
- よくある質問を予測し、先回りして解決する
- 起こりやすい失敗点のトラブルシューティングを含める
- 明確な見出し・リスト・余白でスキャンしやすく書く
- 成功を確認する検証ステップを含める

## Mintlify コンポーネントリファレンス

### docs.json

- docs.json ファイルとサイトナビゲーションを作成する際は [docs.json スキーマ](https://mintlify.com/docs.json) を参照する

### コールアウトコンポーネント

#### Note - 追加の有用情報

<Note>
本文の流れを妨げずに主内容を補足する情報
</Note>

#### Tip - ベストプラクティスとプロ向けヒント

<Tip>
成功率を高める専門的な助言、ショートカット、ベストプラクティス
</Tip>

#### Warning - 重要な注意事項

<Warning>
潜在的な問題、破壊的変更、破壊的な操作に関する重要情報
</Warning>

#### Info - 中立的な文脈情報

<Info>
背景情報、文脈、または中立的なお知らせ
</Info>

#### Check - 成功の確認

<Check>
肯定的な確認、完了、または達成の指標
</Check>

### コードコンポーネント

#### 単一のコードブロック

単一のコードブロックの例:

```javascript config.js
const apiConfig = {
  baseURL: 'https://api.example.com',
  timeout: 5000,
  headers: {
    'Authorization': `Bearer ${process.env.API_TOKEN}`
  }
};
```

#### 複数言語のコードグループ

コードグループの例:

<CodeGroup>
```javascript Node.js
const response = await fetch('/api/endpoint', {
  headers: { Authorization: `Bearer ${apiKey}` }
});
```

```python Python
import requests
response = requests.get('/api/endpoint', 
  headers={'Authorization': f'Bearer {api_key}'})
```

```curl cURL
curl -X GET '/api/endpoint' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```
</CodeGroup>

#### リクエスト／レスポンスの例

リクエスト／レスポンスドキュメントの例:

<RequestExample>
```bash cURL
curl -X POST 'https://api.example.com/users' \
  -H 'Content-Type: application/json' \
  -d '{"name": "John Doe", "email": "[e-mail]"}'
```
</RequestExample>

<ResponseExample>
```json Success
{
  "id": "user_123",
  "name": "John Doe", 
  "email": "[e-mail]",
  "created_at": "2024-01-15T10:30:00Z"
}
```
</ResponseExample>

### 構造コンポーネント

#### 手順用のステップ

ステップバイステップ手順の例:

<Steps>
<Step title="依存関係をインストールする">
  必要なパッケージをインストールするには `npm install` を実行します。
  
  <Check>
  `npm list` を実行してインストールを確認します。
  </Check>
</Step>

<Step title="環境を構成する">
  API 資格情報を含む `.env` ファイルを作成します。
  
  ```bash
  API_KEY=your_api_key_here
  ```
  
  <Warning>
  API キーをバージョン管理にコミットしないでください。
  </Warning>
</Step>
</Steps>

#### 代替コンテンツのためのタブ

タブ付きコンテンツの例:

<Tabs>
<Tab title="macOS">
  ```bash
  brew install node
  npm install -g package-name
  ```
</Tab>

<Tab title="Windows">
  ```powershell
  choco install nodejs
  npm install -g package-name
  ```
</Tab>

<Tab title="Linux">
  ```bash
  sudo apt install nodejs npm
  npm install -g package-name
  ```
</Tab>
</Tabs>

#### 折りたたみ可能コンテンツのためのアコーディオン

アコーディオングループの例:

<AccordionGroup>
<Accordion title="接続問題のトラブルシューティング">
  - **ファイアウォール遮断**: ポート 80 と 443 が開いていることを確認する
  - **プロキシ設定**: HTTP_PROXY 環境変数を設定する
  - **DNS 解決**: DNS サーバーとして 8.8.8.8 を試す
</Accordion>

<Accordion title="高度な設定">
  ```javascript
  const config = {
    performance: { cache: true, timeout: 30000 },
    security: { encryption: 'AES-256' }
  };
  ```
</Accordion>
</AccordionGroup>

### 情報を強調するためのカードとカラム

カードとカードグループの例:

<Card title="はじめにガイド" icon="rocket" href="/quickstart">
インストールから最初の API 呼び出しまでを 10 分以内で案内します。
</Card>

<CardGroup cols={2}>
<Card title="認証" icon="key" href="/auth">
  API キーまたは JWT トークンを用いたリクエストの認証方法を学びます。
</Card>

<Card title="レート制限" icon="clock" href="/rate-limits">
  レート制限と大量トラフィック時のベストプラクティスを理解します。
</Card>
</CardGroup>

### API ドキュメントコンポーネント

#### パラメータフィールド

パラメータドキュメントの例:

<ParamField path="user_id" type="string" required>
ユーザーの一意の識別子。UUID v4 形式である必要があります。
</ParamField>

<ParamField body="email" type="string" required>
ユーザーのメールアドレス。システム内で有効かつ一意である必要があります。
</ParamField>

<ParamField query="limit" type="integer" default="10">
返す結果の最大数。範囲：1〜100。
</ParamField>

<ParamField header="Authorization" type="string" required>
API 認証用のベアラートークン。形式：`Bearer YOUR_API_KEY`
</ParamField>

#### レスポンスフィールド

レスポンスフィールドのドキュメント例:

<ResponseField name="user_id" type="string" required>
新しく作成されたユーザーに割り当てられる一意の識別子。
</ResponseField>

<ResponseField name="created_at" type="timestamp">
ユーザーが作成された時刻の ISO 8601 形式のタイムスタンプ。
</ResponseField>

<ResponseField name="permissions" type="array">
このユーザーに割り当てられた権限文字列の一覧。
</ResponseField>

#### 展開可能な入れ子フィールド

入れ子フィールドのドキュメント例:

<ResponseField name="user" type="object">
関連データを含む完全なユーザーオブジェクト。

<Expandable title="ユーザーのプロパティ">
  <ResponseField name="profile" type="object">
  個人情報を含むユーザープロフィール情報。
  
  <Expandable title="プロフィール詳細">
    <ResponseField name="first_name" type="string">
    登録時に入力したユーザーの名。
    </ResponseField>
    
    <ResponseField name="avatar_url" type="string | null">
    ユーザーのプロフィール画像の URL。アバターが未設定の場合は null を返します。
    </ResponseField>
  </Expandable>
  </ResponseField>
</Expandable>
</ResponseField>

### メディアと高度なコンポーネント

#### 画像用フレーム

すべての画像をフレームで囲む:

<Frame>
<img src="/images/dashboard.png" alt="Main dashboard showing analytics overview" />
</Frame>

<Frame caption="分析ダッシュボードはリアルタイムのインサイトを提供します">
<img src="/images/analytics.png" alt="Analytics dashboard with charts" />
</Frame>

#### 動画

自前ホスティングの動画コンテンツには HTML の video 要素を使用します:

<video
  controls
  className="w-full aspect-video rounded-xl"
  src="link-to-your-video.com"
></video>

YouTube 動画は iframe 要素で埋め込みます:

<iframe
  className="w-full aspect-video rounded-xl"
  src="https://www.youtube.com/embed/4KzFe50RQkQ"
  title="YouTube 動画プレーヤー"
  frameBorder="0"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
  allowFullScreen
></iframe>

#### ツールチップ

ツールチップの使用例:

<Tooltip tip="アプリケーションプログラミングインターフェース - ソフトウェアを構築するためのプロトコル">
API
</Tooltip>

#### 更新情報

更新情報は変更履歴に使用します:

<Update label="Version 2.1.0" description="2024年3月15日リリース">
## 新機能
- ユーザーの一括インポート機能を追加
- 実行可能な提案を含むエラーメッセージを改善

## バグ修正
- 大規模データセットでのページネーション問題を修正
- 認証のタイムアウト問題を解消
</Update>

## 必須のページ構成

すべてのドキュメントページは YAML フロントマターから始める必要があります:

```yaml
---
title: "明確で具体的、かつキーワード豊富なタイトル"
description: "ページの目的と価値を簡潔に説明する記述"
---
```

## コンテンツ品質の基準

### コード例の要件

- ユーザーがコピーして実行できる、完全で実行可能な例を常に含める
- 適切なエラーハンドリングとエッジケース対応を示す
- プレースホルダーではなく現実的なデータを使用する
- 検証用に期待される出力や結果を含める
- 公開前にすべてのコード例を十分にテストする
- 必要に応じて言語を指定し、ファイル名も記載する
- 複雑なロジックには説明コメントを追加する
- コード例に実際の API キーや秘密情報を含めない

### API ドキュメントの要件

- 任意項目を含むすべてのパラメータを明確な説明付きで記載する
- 成功時とエラー時のレスポンス例を現実的なデータで示す
- 具体的な数値を含むレート制限情報を記載する
- 正しい形式を示す認証の例を提供する
- すべての HTTP ステータスコードとエラーハンドリングを説明する
- リクエスト／レスポンスの一連の流れを網羅する

### アクセシビリティ要件

- すべての画像や図に説明的な代替テキストを含める
- 「ここをクリック」ではなく具体的で行動可能なリンクテキストを使用する
- H2 から始まる適切な見出し階層を保つ
- キーボード操作の考慮事項を提供する
- 例やビジュアルで十分な色コントラストを使用する
- 見出しとリストでスキャンしやすい構成にする

## コンポーネント選定ロジック

- 手順や順序立った説明には **Steps** を使用する
- プラットフォーム別コンテンツや代替手法には **Tabs** を使用する
- 同一の概念を複数のプログラミング言語で示す場合は **CodeGroup** を使用する
- 情報の段階的開示には **Accordions** を使用する
- API エンドポイントのドキュメントには **RequestExample/ResponseExample** を使用する
- API パラメータには **ParamField**、API レスポンスには **ResponseField** を使用する
- 入れ子のオブジェクトプロパティや階層情報には **Expandable** を使用する