Kindle Ranking Bot Development Guide

You are assisting with a Python bot that scrapes Amazon's Kindle bestseller rankings and sends daily notifications via Discord WebHook. The bot runs automatically every day at 12:00 JST using GitHub Actions.

🚨 Critical Rules - MUST FOLLOW

Git Commit Protocol (MANDATORY)

1. **Commit frequently in small, logical units**

- 1 logical change = 1 commit

- Multiple files OK if same purpose

- Different purposes = separate commits

2. **Never mix different types of work in one commit**

- ❌ Feature addition (feat) + refactoring (refactor)

- ❌ Bug fix (fix) + test addition (test)

- ✅ Each work type in separate commits

3. **Commit message format (STRICT)**

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

- Prefixes:

- `feat`: New features

- `fix`: Bug fixes

- `refactor`: Code refactoring

- `test`: Test additions/modifications

- `docs`: Documentation changes

- `style`: Code formatting

- `chore`: Miscellaneous changes

4. **Pre-commit checklist**

- Run related tests to verify functionality

- Confirm it's a single logical change unit

- Verify commit message is appropriate

Development Rules

Branch Workflow

Creating Feature Branch

```bash

git checkout main

git pull origin main

git checkout -b Prefix/<branch-name>

```

Committing Changes

```bash

git commit -m "Prefix: <change summary in Japanese>"

```

Creating Pull Request

```bash

git push -u origin <branch-name>

gh pr create --title "[Prefix]<title>" --body "<description>"

```

Branch Prefixes

Project Structure

Core Components

**src/main.py**: Application entry point

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

**src/notifier.py**: Discord notification sender

**src/summarizer.py**: AI-powered summary generation

**src/config.py**: Configuration management

Testing Infrastructure

**tests/test_scraper.py**: Comprehensive unit tests

**run_tests.py**: Test runner with modes:

Common Commands

Development with uv (Primary)

```bash

Install uv

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

Setup environment and install dependencies

uv sync

Run bot locally

uv run python src/main.py

Format code with ruff

uv run ruff format .

Add dependencies

uv add package-name

uv add --dev dev-package-name

```

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 (5 iterations)

uv run python run_tests.py --stress 5

All test modes

uv run python run_tests.py --all

```

Legacy pip Commands (Compatibility)

```bash

pip install -e .

python run_tests.py --quick

```

Environment Variables

Required

Optional

GitHub Actions

**daily-ranking.yml**: Scheduled daily execution at 12:00 JST

**test.yml**: Automated testing on push and pull requests

Code Review Guidelines

When reviewing pull requests:

1. Check current open pull requests

2. Read thoroughly:

- `prompt/code_review_guide.md`: Review guidelines

- `prompt/reviewer_personality.md`: Review persona

3. Post review comments in Japanese on the PR

Important Constraints

Step-by-Step Workflow

1. **Receive task**: Understand requirements

2. **Create branch**: Follow prefix convention

3. **Make changes**: Small, logical commits with proper prefixes

4. **Format code**: Run `ruff format .`

5. **Test**: Run appropriate tests with uv

6. **Update docs**: Keep CLAUDE.md current

7. **Push & PR**: Create pull request when ready

8. **Sound notification**: Execute afplay command before idle