ポイ活エージェント — Claude Code プロジェクト

Claude Code の サブエージェント と skill で構成された、ポイ活案件の収集・正規化・告知・記事生成パイプライン。

---

アーキテクチャ

依頼 (Claude Code)
   │
   ▼
サブエージェント (.claude/agents/*.md)  ← 薄いオーケストレーター
   │  (skill を順番に呼ぶだけ)
   ▼
skill (.claude/skills/<name>/SKILL.md)  ← 実処理 (TypeScript コード骨格を内包)
   │
   ▼
プロジェクトの実コード (skills/ / lib/ / app/)

設計の核: サブエージェントには判断だけを書き、処理は全部 skill に寄せる。新サイト追加・新ページ追加・新検査追加は、skill 1個の編集 (または1個追加) で完結する。

---

サブエージェント (8個)

詳細は agents-and-skills-design.md を参照。

---

skill (36個)

.claude/skills/
├── 設定基盤
│   └── config-loader               ← env を一元管理 (process.env を読むのはここだけ)
│
├── データ取得
│   ├── jina-reader                 ← r.jina.ai のラッパ
│   ├── point-site-extractor        ← サイト別パーサ (ディスパッチ)
│   └── rate-limiter                ← 連続リクエストのスロットル
│
├── 正規化
│   ├── deal-name-canonicalizer
│   ├── reward-parser               ← 「1,000円 → 1000円」
│   ├── slug-generator              ← URL 用 slug
│   └── category-classifier         ← LLM フォールバック
│
├── 永続化 (Supabase)
│   ├── supabase-sites-repo       ← color / initial / pros / cons / signup_bonus 等 UI 用フィールド込み
│   ├── supabase-deals-repo       ← sub_title / requirements / tags / is_active / last_seen_at
│   ├── supabase-history-repo
│   ├── supabase-articles-repo    ← article_category / read_time / view_count / tags / is_featured
│   └── supabase-codes-repo       ★ v1.2: 紹介コード（招待コード）
│
├── 差分管理 ★ (運用フェーズの主役)
│   ├── deal-diff-detector        ← {added, updated, unchanged, missing} を出す純粋関数
│   ├── deal-deactivator          ← 7日経過した active 案件を inactive 化
│   └── change-summary-formatter  ← 運営者向け日報 (Markdown)
│
├── 集計 ★ v1.2 追加
│   └── deal-history-aggregator   ← 30日推移 / 前日比 / min/max/avg / サイト別比較
│
├── SNS 通知
│   ├── x-poster                    ← Twitter API v2
│   ├── tweet-formatter             ← 280字保護
│   └── post-dedup                  ← tweet_log で重複検査
│
├── コンテンツ生成
│   ├── claude-prompt-runner        ← Anthropic SDK
│   ├── seo-article-template        ← 記事プロンプト
│   └── markdown-quality-check      ← 文字数/H2 数/meta 検査
│
├── SEO・メタ
│   ├── metadata-builder            ← Next.js Metadata
│   ├── jsonld-builder              ← WebSite/Breadcrumb/Product/Article
│   ├── sitemap-generator           ← app/sitemap.ts
│   ├── robots-generator            ← app/robots.ts
│   ├── ogp-image-generator         ← @vercel/og
│   └── breadcrumb-builder
│
├── UI
│   ├── tailwind-token-guard        ← 「白ベース・グリーンアクセント」検査
│   ├── component-scaffold
│   └── nextjs-page-scaffold        ← App Router 雛形
│
└── 検証
    ├── seo-checklist               ← title/description/canonical/JSON-LD
    ├── lighthouse-runner           ← LCP/CLS/INP
    ├── link-checker                ← 404・アフィ URL
    └── ts-strict-validator         ← any/@ts-ignore/process.env

---

セットアップ

1. プロジェクトに配置

このディレクトリ構造を、Claude Code を動かしたい Next.js プロジェクトのルートに配置:

your-nextjs-project/
├── .claude/
│   ├── agents/      ← サブエージェント定義
│   └── skills/      ← skill 定義
├── .env.example
├── .gitignore
├── CLAUDE.md        ← プロジェクト全体規約
└── (Next.js のファイル)

2. 環境変数

cp .env.example .env.local
# 各キーに実値を埋める

3. 依存パッケージ (各 skill が要求)

# Supabase 系
npm i @supabase/supabase-js

# 取得系
npm i undici  # または fetch ポリフィル
npm i p-limit

# AI
npm i @anthropic-ai/sdk

# X
npm i twitter-api-v2

# 検証
npm i -D jsdom @types/jsdom lighthouse chrome-launcher

# UI
npm i @vercel/og
npm i zod  # config-loader 用

4. Claude Code で起動

このディレクトリで claude コマンドを実行。サブエージェントは自動で発見されます。

# 例
> scraper エージェントで全サイトを巡回して
> page-builder で /category/[category] のページを作って
> seo-auditor でデプロイ前チェックを走らせて

---

設計上の固い約束

1. process.env の直接参照は config-loader skill 内のみ

• 他で書いたら ts-strict-validator が CI で落とす
• 環境変数の追加・改名は config-loader/schema.ts の編集だけで済む

1. サブエージェントに処理ロジックを書かない

• サブエージェントは skill を順番に呼ぶ司令塔
• 「Jina で取得 → パース → DB 保存」は 3 個の skill (jina-reader / point-site-extractor / supabase-deals-repo) を順番に呼ぶだけ

1. skill の責務は単一

• tweet-formatter は文字列を作るだけ (X API は触らない)
• x-poster は投稿するだけ (フォーマットも重複検査もしない)
• 組み合わせは呼び出し側 (サブエージェント) の仕事

1. 白ベース・グリーンアクセントを守る

• tailwind-token-guard がページ内のクラス名を検査
• bg-purple-* bg-pink-* 等は禁止
• グリーンの広面積背景 (min-h-screen bg-green-600 等) も禁止

1. CLAUDE.md がプロジェクト全体規約の唯一のソース

• 各 skill / エージェントは CLAUDE.md を参照する形で書く
• CLAUDE.md と矛盾する記述は skill 側を直す

---

デプロイ前チェックリスト

# 型違反検査
npm run lint:ts-strict

# Tailwind 色規約検査
npm run lint:tailwind

# SEO/Lighthouse/リンク 一括検査 (Claude Code で seo-auditor を起動)
> seo-auditor でデプロイ前チェックを走らせて

すべて緑になってからデプロイ。