Kindle Rank Bot Development Assistant

Development assistant for the kindle-rank-bot repository - a Python bot that scrapes Amazon's Kindle bestseller rankings and sends daily notifications via Discord WebHook using GitHub Actions.

🚨 Critical Git Workflow Rules (Must Follow)

1. Commit Frequently in Small Units

2. Never Mix Different Types of Changes

❌ **NEVER DO:**

✅ **ALWAYS DO:**

3. Commit Message Format (STRICT)

Format: `prefix: 日本語で説明`

**Prefix types:**

4. Pre-Commit Checklist

Project Workflow Rules

Branch Management

1. **NEVER work on main branch**

2. Always create feature branch:

```bash

git checkout main

git pull origin main

git checkout -b Prefix/<branch-name>

```

3. Branch prefix conventions:

- `feature/`: New features

- `update/`: Improvements

- `bugfix/`: Minor fixes

- `hotfix/`: Critical fixes

- `refactor/`: Code refactoring

- `test/`: Test work

- `docs/`: Documentation

- `chore/`: Maintenance

Development Workflow

1. Create branch from main

2. Make changes with frequent commits

3. Run tests after each change

4. Format code with ruff after each change

5. Push when ready (after all commits complete)

6. Before returning to waiting state: **ALWAYS run** `afplay /Users/kimuranaoto/Music/notice.mp3`

7. Unless specified otherwise, work until just before git push (after completing all commits)

Code Quality

```bash

uv run ruff format .

```

Development Commands

Setup & Dependencies

```bash

Install uv (if needed)

curl -LsSf https://astral.sh/uv/install.sh | sh

Install dependencies

uv sync

Add new dependencies

uv add package-name

Add dev dependencies

uv add --dev package-name

```

Running the Bot

```bash

Run locally (requires DISCORD_WEBHOOK_URL)

uv run python src/main.py

```

Testing

```bash

Run all unit tests

uv run python run_tests.py

Quick test (1 item)

uv run python run_tests.py --quick

Stress test (multiple runs)

uv run python run_tests.py --stress 5

All test types

uv run python run_tests.py --all

```

Code Formatting

```bash

Format all code

uv run ruff format .

```

Project Architecture

Core Components

1. **src/main.py**: Entry point with orchestration

- Error handling and logging

- System exit on failure for GitHub Actions

- Gemini API integration for summaries

2. **src/scraper.py**: Amazon Kindle ranking scraper

- Fetches top 10 from https://www.amazon.co.jp/gp/bestsellers/digital-text/2275256051/

- Extracts: title, rating, review count, price, URL

- Retry mechanism (max 3 attempts, exponential backoff)

- Graceful handling of missing data

3. **src/notifier.py**: Discord WebHook sender

- Environment variable validation

- Detailed error messages

4. **src/summarizer.py**: Gemini AI summaries

- Ranking analysis and insights

- Graceful fallback on failure

- Configurable via environment variables

5. **src/config.py**: Centralized configuration

- Environment variable management

- Validation and defaults

Testing Files

GitHub Actions

Environment Variables

Required

Optional

Pull Request Review Process

When reviewing PRs:

1. Check current open pull requests

2. Read these files thoroughly:

- `prompt/code_review_guide.md`: Review guidelines

- `prompt/reviewer_personality.md`: Review persona

3. Post review comments in Japanese on the PR

Key References

Task Execution Checklist

✅ Work on feature branch (not main)

✅ Commit frequently in small logical units

✅ Use proper commit message prefix

✅ Run tests after changes

✅ Format with ruff after changes

✅ Keep CLAUDE.md updated

✅ Play notification sound before returning to waiting state

✅ Work until ready to push (unless told otherwise)