思い立って、DevRev の「あるある」を集めるナレッジサイトを作ることにしました

せっかくなので、どんな風に Web サイトを構築していくかをこの連載で書いていきます。フレームワークを決めるところからデプロイまで、AI（Cursor）と一緒に進めたログです

今回の第1回は、相棒になる Cursor の開発環境を整えるところから

この連載で作っているもの

ざっくり言うと、DevRev を使っていて困った「あ、それあるある」っていう話を、1件ずつ並べるサイトをつくります

ブログみたいに新着を読ませるより、症状やキーワードで探す使い方を想定しています

あるある一覧のイメージ（手書き風）

症状やキーワードで探せるあるある一覧のイメージ（概念図）

なぜいきなり環境の話から？

「あるあるサイトのトップ、作って」と Cursor に頼むだけだと、毎回説明がぶれます

どのディレクトリに何を置くか
Cursor に毎回なんと説明するか
PAT みたいなトークンをチャットに貼っていいのか

こういうあたりまえを、先にルールとドキュメントに残しておくと、その後のセッションがだいぶ楽になりました

flowchart LR subgraph prep [整える土台] RULE[Cursor ルール] OPS[運用マスター] SKILL[Cursor スキル] end subgraph next [次の回以降] IA[サイト構成] ASTRO[骨組み] DEPLOY[公開] end prep --> IA --> ASTRO --> DEPLOY

あるあるサイト用リポの構成

Cursor で開くのは、あるあるサイト用のリポジトリ1本。中身はだいたい次のイメージです

あるあるサイト用リポ/
├── docs/
│   ├── OPERATIONS.md          … 運用ルールの正本
│   └── internal/verification/ … DevRev 検証ログ（非公開）
├── .cursor/
│   ├── rules/                 … Cursor への指示
│   └── skills/                … 繰り返し作業の手順書（Skills）
└── web/                       … サイト本体（次回以降で育てる）

サイトのコードも運用ルールも検証ログも、ひとまとめにしておくと Cursor に「このリポを見て」と言うだけで済みます

役割の切り分け（ざっくり）

置き場所	何を入れるか
`docs/OPERATIONS.md`	サイト運用・匿名化・投稿フローなど
`web/`	フレームワーク・ページ・あるあるデータ
`.cursor/rules/`	毎回チャットで説明したくない前提
`.cursor/skills/`	繰り返し作業の手順書（Cursor Skills）
`docs/internal/verification/`	「動いた／動かない」の検証メモ

「正本はどこ？」と迷わないよう、ドキュメントは docs/ 、コードは web/ と決めておきました

運用ドキュメントと Cursor ルール

OPERATIONS.md を正本にした

サイトの運用方針や匿名化のルールは、docs/OPERATIONS.md に集約した

Cursor に作業を頼むときは、まずここを読ませる。毎回チャットで口頭説明しなくてよくなる

.cursor/rules に書いておくこと

OPERATIONS.md は人間向けの正本、.cursor/rules/ は Cursor が毎セッション自動で読む前提の置き場です

書いておくと効いたのは、だいたい次のあたり

リポのどこに何があるか（docs/ が正本、web/ がサイト本体、など）
PAT や API トークンをチャットに貼らない（.env と Skills で渡す — 後述）
あるあるの内容を公開するときの匿名化のざっくり方針

ルールは長くしすぎない。毎回説明したくないことだけ残すのがコツ

例:

.cursor/rules/
├── project-operations.mdc    … 毎セッションの前提（リポ構成・トークン禁止など）
└── devrev-verification.mdc   … 検証ログを触るときだけ

Cursor のスキルって何？

Rules と並んで、最近 Cursor でよく使うのが Skills です

ざっくり言うと、エージェント向けの手順書を Markdown で置いておく仕組みです。「PR のレビュー手順」「コミットメッセージの型」「このリポでの検証の進め方」みたいな、繰り返しやる作業をチャットで毎回説明しなくてよくなります

Rules との違い

	Rules（`.cursor/rules/`）	Skills（`.cursor/skills/`）
役割	毎セッションの前提・禁止事項	特定タスクの進め方
読まれるタイミング	だいたい常時	その作業のとき
例	リポ構成、トークン禁止	デプロイ手順、記事レビュー

「いつも守ってほしいこと」は Rules、「たまにだけ踏む手順」は Skills——くらいで分けると整理しやすいです

どこに置くか

種類	パス	スコープ
個人用	`~/.cursor/skills/`	自分の全プロジェクト
プロジェクト用	`.cursor/skills/`	そのリポを開いた人と共有

1つの作業用フォルダに SKILL.md を置く形です。frontmatter に name と description を書くと、Cursor が「いつ使うか」を判断しやすくなります

my-skill/
└── SKILL.md    … 手順の本文（YAML frontmatter + Markdown）

この連載ではどう使うか

あるあるサイト用リポの .cursor/skills/ には、サイト構築・執筆・検証で何度も使う手順を足していく想定です

今回の第1回では中身までは書かない。まず Rules で土台、Skills で手順 の2段構えがある、と知っておけば十分です

トークンは `.env` とスキルで渡す

Rules で「トークンをチャットに貼らない」と決めたあと、実際に API を叩かせたいときは .env に置いて、Skill に読み方を書く のが現実的です

「貼らない」だけだと困る。置き場所と手順をセットで決めておくのがポイント

やり方	内容
`.env` に書く	トークンはリポ直下や `skills/` 付近の `.env` に置く。`.gitignore` でコミット対象外にする
`.env.example` を置く	キー名だけ書いた雛形をリポに載せ、値は各自がローカルで埋める
スキルに手順を書く	「`.env` を読んで API を叩く」流れを `SKILL.md` にまとめ、チャットで毎回説明しない

Skill に「どの環境変数を、どう export するか」まで書いておけば、Cursor は手順どおり動ける。会話ログにトークンが残りにくいのもメリットです

.env.example はだいたいこんな感じ（値は各自がローカルで埋める）

# .env.example（値は空のままコミットしない）
DEVREV_PAT=

今回の HACK+PLUS

環境づくりを進めてみて、「ここは Cursor」「ここは自分」と分かれたのでメモ

HACK（新しい発見）

OPERATIONS.md の草案と .cursor/rules の文案をたたき台として出す
ディレクトリ構成のたたき台を出して、人間が「ここは docs、ここは web」と決める
Rules（常時の前提）と Skills（繰り返し手順） を分けると、説明のぶれが減る
AI は選択肢を並べるのが速い。リポの形とルールの境界は人間が先に引くと、その後が楽になる

PLUS（ハマりどころ・次の一手）

トークンはチャットに貼らず、.env + .gitignore + スキルで渡す（.env.example でキー名だけ共有）
.cursor/rules は長くしすぎない（毎回説明したくないことだけ）
docs/ と web/ の役割は人間が先に決める（たたき台をそのまま採用しない）
次回: 「AIと一緒にサイト構成を決める」で情報設計——ナレッジベース型、ページ構成、2系統コンテンツ