Raindrop API
  ↓
fetch raindrops
  ↓
diff check / state management
  ↓
fetch URL content
  ↓
extract article body
  ↓
fallback simple summary input generation
  ↓
LLM summarization
  ↓
store article JSON
  ↓
build HTML output

raindrop-collection-summarizer/
├─ README.md
├─ pyproject.toml
├─ .env.example
├─ src/
│  ├─ main.py
│  ├─ config.py
│  ├─ models.py
│  ├─ logging_util.py
│  ├─ raindrop_client.py
│  ├─ state_store.py
│  ├─ content_fetcher.py
│  ├─ content_extractor.py
│  ├─ summarizer.py
│  ├─ article_repository.py
│  ├─ html_builder.py
│  └─ utils/
│     ├─ hashing.py
│     ├─ text.py
│     └─ time.py
├─ prompts/
│  ├─ summarize_full.txt
│  └─ summarize_fallback.txt
├─ data/
│  ├─ raw/
│  │  └─ latest_raindrops.json
│  ├─ articles/
│  │  └─ {raindrop_id}.json
│  └─ output/
│     ├─ articles.json
│     └─ latest_summary.json
├─ state/
│  └─ index.json
├─ docs/
│  ├─ index.html
│  ├─ styles.css
│  └─ app.js
└─ .github/
   └─ workflows/
      └─ build.yml

RAINDROP_TOKEN=
RAINDROP_COLLECTION_ID=
LLM_PROVIDER=openai
LLM_API_KEY=
LLM_MODEL=
MAX_SUMMARIZE_PER_RUN=30
REQUEST_TIMEOUT_SECONDS=20
USER_AGENT=RaindropSummarizer/0.1
OUTPUT_DIR=docs
DATA_DIR=data
STATE_DIR=state
LOG_LEVEL=INFO

{
  "raindrop_id": 123456789,
  "collection_id": 111111,
  "title": "Example title",
  "url": "https://example.com/article",
  "domain": "example.com",
  "created_at": "2026-03-25T00:00:00Z",
  "tags": [],
  "excerpt": "short excerpt"
}

{
  "raindrop_id": 123456789,
  "title": "記事タイトル",
  "url": "https://example.com/article",
  "topic": "AI と検索体験の変化",
  "summary_3lines": ["1行目", "2行目", "3行目"],
  "priority": "medium",
  "read_now_reason": "...",
  "defer_reason": "...",
  "drop_candidate": false,
  "keywords": ["AI", "検索", "プロダクト"],
  "model_provider": "openai",
  "model_name": "gpt-4.1-mini",
  "summarized_at": "2026-03-25T08:31:00Z"
}

{
  "last_run_at": "2026-03-25T08:31:00Z",
  "items": {
    "123456789": { "status": "summarized", "content_hash": "sha256:..." },
    "987654321": { "status": "skipped", "reason": "summary_input_unavailable" }
  }
}

# CLAUDE.md

必ず日本語で回答してください。

## Project

Tsuyu-mi — Raindrop.io コレクションの記事を取得・本文抽出・AI 要約し、HTML 一覧を出力するバッチツール。

## Tech Stack

Python 3.11+ / httpx / pydantic / trafilatura / readability-lxml / jinja2 / click / rich

## Commands

- Install: `pip install -e ".[dev]"`
- Run: `python -m src.main run`
- Test: `pytest`
- Lint: `ruff check src/ tests/`

## References

- 詳細ルール: `.claude/rules/` (自動読み込み)
- アーキテクチャ・設計方針: `.steering/`
- 仕様書: `docs/specs/`

---
name: update-specs
description: コード変更に関連する docs/specs/ の仕様書を更新する。コード変更の完了時に自動で実行する。
context: fork
---

変更されたファイルに関連する `docs/specs/` 配下の仕様書を特定し、更新案を提示する。

## 手順

1. `git diff --name-only HEAD` で変更されたファイル一覧を取得する（Python ファイル、およびファイルのリネーム・移動・削除を含む）
2. `docs/specs/` 配下の各仕様書を読み込み、変更ファイルのパスや関連モジュール名が含まれるものを特定する。対応表:
   - `src/config.py`, `src/logging_util.py` → `01_overview.md`
   - `src/models.py` → `02_data_models.md`
   - `src/raindrop_client.py` → `03_api_integration.md`
   - `src/content_fetcher.py`, `src/content_extractor.py` → `04_content_extraction.md`
   - `src/summarizer.py`, `prompts/` → `05_summarization.md`
   - `src/html_builder.py`, `docs/` (specs以外) → `06_html_output.md`
   - `src/state_store.py`, `src/article_repository.py` → `07_state_management.md`
   - `src/main.py` → `08_cli_interface.md`
3. 関連する仕様書が見つからない場合、新機能の可能性がある。変更ファイルのパスとディレクトリ構造から機能名を推定し、`docs/specs/` への新規仕様書の作成を提案する
4. 関連する仕様書と変更された Python ファイルの内容を読み込む
5. 仕様書の各セクション（データモデル、フロー、ビジネスルール等）が変更内容と整合しているか確認する
6. 乖離がある場合は、セクションごとに具体的な更新案を提示する
7. ファイルのリネーム・移動・削除があった場合、`git diff --diff-filter=RD --name-status HEAD` で検出し、全仕様書・README.md・CLAUDE.md・`.steering/` 内に旧パスの記載が残っていないか確認する。残っていれば新パスへの更新（または削除済みの旨の反映）を提示する
8. `README.md` を読み込み、変更内容に関連する記載（機能一覧、技術スタック、セットアップ手順等）が最新と合っているか確認する。更新が必要であれば合わせて提示する
9. `CLAUDE.md` を読み込み、変更内容に関連する記載（Tech Stack、Commands 等）が最新と合っているか確認する。更新が必要であれば合わせて提示する
10. `.steering/` 配下のファイル（`architecture.md`, `data-models.md`, `llm-guidelines.md`）を読み込み、変更内容と整合しているか確認する。更新が必要であれば合わせて提示する

## 報告形式

以下の形式で報告する:

- **変更ファイル数**: N件
- **関連する仕様書**: 該当する仕様書のパス一覧（なければ「なし」）
- **更新が必要な箇所**:
  - 仕様書のパス・セクション名・現在の記載・更新案を記載
- **更新不要の場合**: 「仕様書は最新の状態です」と報告
- **新規作成の提案**（関連仕様書が見つからない場合）:
  - 推定した機能名と配置先パス
  - 仕様書の草案
- **パス変更の追従**: リネーム・移動・削除されたファイルの旧パスがドキュメント内に残っていれば、対象ファイルと更新案を記載
- **README.md の更新**: 必要あり/なし（必要な場合は更新案を記載）
- **CLAUDE.md の更新**: 必要あり/なし（必要な場合は更新案を記載）
- **.steering/ の更新**: 必要あり/なし（必要な場合は対象ファイルと更新案を記載）

---
description: Git 運用規範（daily-tech-news 準拠）
---

# Git 運用規範

## ブランチ戦略

- Issue 作成 → `feature/issue-XX-description` ブランチ → PR → マージ
- main ブランチへの直接コミットは避ける

## PR ルール

- タイトル: 絵文字 + 概要 + `(#Issue番号)`
  - ✨ 新機能 / 🐛 バグ修正 / 📚 ドキュメント / ⚡ パフォーマンス / ♻️ リファクタ
- 本文冒頭: `Closes #番号`

## ラベル

- `enhancement` (#a2eeef): 新機能
- `bug` (#d73a49): バグ修正
- `documentation` (#0075ca): ドキュメント
- `performance` (#0e8a16): 最適化

## コミットメッセージ

- 日本語または英語で簡潔に
- 変更の「何を」「なぜ」が分かるように

---
description: Python コーディング規約
globs: "src/**/*.py,tests/**/*.py"
---

# コーディング規約

## スタイル

- Python 3.11+ の機能を活用（type union `X | Y`、`match` 文など）
- ruff でリント（line-length=100）
- 型ヒントを付ける（Pydantic モデルは必須、ユーティリティ関数も推奨）

## エラーハンドリング

- 記事単位で try-except + 続行（1 記事の失敗でパイプライン全体を止めない）
- 失敗理由を state に記録し、次回再試行可能にする
- ログは `logging_util.py` のロガーを使う

## モジュール構成

- `src/models.py` が全モジュール共通の型定義層
- 依存の方向は上位（main.py）→ 下位（utils/）。循環依存禁止
- LLM プロバイダーは Protocol + Factory パターンで抽象化

---
description: 実装ワークフローのルール
---

# 実装ワークフロー

## ステップごとの進め方

1. Issue を作成する
2. `feature/issue-XX-description` ブランチを切る
3. 実装する
4. `/update-specs` で仕様書との乖離をチェックし、必要なら更新する
5. Test plan の項目をローカルで実行し、動作確認する
6. コミット・プッシュ → PR 作成（確認済みの結果を PR に記載）
7. マージ後、main に戻って次のステップへ

## Claude Code 関連の作業時

Skill（`.claude/skills/`）、ルール（`.claude/rules/`）、CLAUDE.md、仕様ドキュメントの配置など、Claude Code に関わるファイルを作成・変更する際は、**公式ドキュメントを参照して最新の情報を確認してから作業すること**。

Claude Code の仕様（ファイル配置パス、frontmatter 形式など）は変更される可能性があるため、古い知識で進めない。

# アーキテクチャ概要

## 処理パイプライン

Raindrop API → fetch → diff check → fetch URL → extract body → LLM summarize → store JSON → build HTML

## モジュール依存関係

main.py (CLI オーケストレーション)
  ├── config.py          (環境変数)
  ├── logging_util.py    (ロガー)
  ├── raindrop_client.py (API 取得)
  ├── state_store.py     (差分管理)
  ├── content_fetcher.py (HTML 取得)
  ├── content_extractor.py (本文抽出)
  ├── summarizer.py      (LLM 要約)
  ├── article_repository.py (JSON 保存)
  └── html_builder.py    (HTML 生成)

## 設計判断

| 項目 | 判断 | 理由 |
|---|---|---|
| 同期/非同期 | 同期 | MVP は 30 件上限。まず動くものを優先 |
| LLM 抽象化 | Protocol + Factory | SDK の違いを各 Provider 内に閉じ込め |
| JSON 保存 | 1 記事 = 1 ファイル | reprocess が容易 |
| HTML 出力先 | docs/ | GitHub Pages 対応 |
| プロンプト | 外部ファイル prompts/*.txt | コード変更なしで調整可能 |

# データモデル概要

## 記事の状態遷移

pending → fetched → extracted → summarized
                  ↘ fallback_ready ↗
          ↘ skipped (理由付き)
          ↘ failed (エラーログ付き)

## スキップ理由

- fetch_failed: URL 取得失敗
- extract_failed: 本文抽出失敗
- summary_input_unavailable: 簡易要約用入力も不足
- unsupported_video: 動画コンテンツ
- unsupported_non_html: 非 HTML コンテンツ
- llm_failed: LLM 応答失敗
- too_short: 本文が短すぎる

## 主要モデル

- RaindropItem: Raindrop API レスポンスの内部表現
- ProcessedArticle: 処理済み記事の正本（data/articles/{id}.json）
- SummaryResult: LLM 出力の JSON スキーマ
- StateEntry / StateIndex: 差分管理用（state/index.json）

# LLM プロバイダーガイドライン

## プロバイダー切り替え

- LLM_PROVIDER 環境変数で openai / gemini / anthropic を指定
- LLMProvider Protocol を実装した各プロバイダークラスで抽象化
- Factory 関数で config に基づきインスタンス生成

## プロンプト設計方針

- プロンプトは prompts/ ディレクトリに外部ファイルとして管理
- summarize_full.txt: 本文全文がある場合
- summarize_fallback.txt: メタデータのみの場合
- テンプレート変数: {title}, {url}, {domain}, {text} 等を str.format() で埋め込み

## 出力仕様

- 常に日本語で出力
- JSON 形式を要求し、パース + Pydantic でバリデーション
- 出力スキーマ: topic, summary_3lines, priority, read_now_reason, defer_reason, drop_candidate, drop_reason, keywords

## 本文長による要約モード

- 1500 文字以上: 通常要約（summarize_full.txt）
- 500〜1499 文字: 短文要約（同プロンプト、短め指示）
- 500 文字未満: 簡易要約寄り
- 取得不能: fallback プロンプト（summarize_fallback.txt）

あなたは記事要約アシスタントです。以下の記事を日本語で要約してください。

## 記事情報

- タイトル: {title}
- URL: {url}
- ドメイン: {domain}

## 本文

{text}

## 指示

以下の JSON 形式で出力してください。JSON 以外は出力しないでください。

- topic: 記事の主題を1行で
- summary_3lines: 3行の要約（各行は簡潔に。感想文ではなく内容紹介。事実不明な断定を避ける）
- priority: "high" / "medium" / "low"
  - high: 新規性が高い、関心領域と近い、本文を読む価値がある
  - medium: 要点把握で十分、時間があれば読む価値がある
  - low: 重複度が高い、関心軸から遠い、速報性が過ぎている
- read_now_reason: 今読む価値がある理由（1文）
- defer_reason: 後回しでよい理由（1文）
- drop_candidate: true/false（読む価値が薄い場合 true）
- drop_reason: ドロップ候補の理由（該当しなければ空文字）
- keywords: 記事のキーワード3〜5個

あなたは記事要約アシスタントです。以下の記事のメタデータから、日本語で簡易要約を生成してください。

**注意: 本文は取得できていません。メタデータのみに基づく簡易要約です。**

## メタデータ

{metadata}

## 指示

以下の JSON 形式で出力してください。JSON 以外は出力しないでください。
本文未取得のため、断定的な表現を避け、メタデータから読み取れる範囲で要約してください。

pending → fetched → extracted → summarized
                  ↘ fallback_ready ↗
          ↘ skipped
          ↘ failed

{
  "raindrop_id": 123456789,
  "collection_id": 111111,
  "title": "Example title",
  "url": "https://example.com/article",
  "domain": "example.com",
  "created_at": "2026-03-25T00:00:00Z",
  "tags": [],
  "excerpt": "short excerpt",
  "type": "link",
  "cover": "",
  "note": ""
}

{
  "topic": "主題",
  "summary_3lines": ["1行目", "2行目", "3行目"],
  "priority": "high",
  "read_now_reason": "今読む価値の理由",
  "defer_reason": "後回しでよい理由",
  "drop_candidate": false,
  "drop_reason": "",
  "keywords": ["キーワード1", "キーワード2", "キーワード3"]
}

{
  "raindrop_id": 123456789,
  "collection_id": 111111,
  "title": "記事タイトル",
  "url": "https://example.com/article",
  "domain": "example.com",
  "created_at": "2026-03-25T00:00:00Z",
  "fetched_at": "2026-03-25T08:30:00Z",
  "source_language": "en",
  "output_language": "ja",
  "content_type": "article",
  "content_status": "ok",
  "fetch_status": "ok",
  "extract_method": "trafilatura",
  "content_chars": 6842,
  "content_hash": "sha256:...",
  "summary_input_type": "fulltext",
  "topic": "AI と検索体験の変化",
  "summary_3lines": [
    "この記事は〜について述べている。",
    "主な論点は〜である。",
    "実務上は〜という示唆がある。"
  ],
  "priority": "medium",
  "read_now_reason": "最近の関心領域と近く、今後の発信や調査に活かしやすいため。",
  "defer_reason": "要点把握だけでも十分で、緊急性は高くないため。",
  "drop_candidate": false,
  "drop_reason": "",
  "keywords": ["AI", "検索", "プロダクト"],
  "model_provider": "openai",
  "model_name": "gpt-4.1-mini",
  "summarized_at": "2026-03-25T08:31:00Z",
  "manual_status": "untriaged",
  "notes": ""
}

{
  "last_run_at": "2026-03-25T08:31:00Z",
  "items": {
    "123456789": {
      "status": "summarized",
      "content_hash": "sha256:...",
      "summarized_at": "2026-03-25T08:31:00Z"
    },
    "987654321": {
      "status": "skipped",
      "reason": "summary_input_unavailable",
      "updated_at": "2026-03-25T08:31:00Z"
    }
  }
}

GET https://api.raindrop.io/rest/v1/raindrops/{collectionId}

1. HTTP GET で HTML 取得
2. trafilatura で本文抽出
3. readability-lxml でフォールバック
4. タイトル / excerpt / URL / domain / tags で簡易要約入力を構成
5. すべて失敗 → スキップ

trafilatura.extract(html, include_comments=False, include_tables=True)

from readability import Document
doc = Document(html)
doc.summary()  # HTML → テキスト変換が必要

class LLMProvider(Protocol):
    def generate(self, prompt: str) -> str: ...

def create_provider(config: Config) -> LLMProvider:
    match config.llm_provider:
        case "openai": return OpenAIProvider(config)
        case "gemini": return GeminiProvider(config)
        case "anthropic": return AnthropicProvider(config)

[Raindrop API取得]
    ↓
  pending ──→ fetched ──→ extracted ──→ summarized
    │            │           │
    │            │           └→ fallback_ready → summarized
    │            │
    │            └→ skipped (fetch_failed)
    │            └→ failed
    │
    └→ skipped (unsupported_video, unsupported_non_html)

{
  "last_run_at": "ISO8601",
  "items": {
    "{raindrop_id}": {
      "status": "summarized | skipped | failed | pending",
      "content_hash": "sha256:... | null",
      "reason": "スキップ理由 | null",
      "summarized_at": "ISO8601 | null",
      "updated_at": "ISO8601"
    }
  }
}

Raindrop API の ID 一覧 - index.json の既存 ID = 新規記事

python -m src.main <command>

python -m src.main run

python -m src.main fetch-only

python -m src.main build-html

python -m src.main reprocess --id 123456789

python -m src.main reprocess-failed