Contributing & Rules

Documentation Update Rule

When making code changes, always update the relevant docs in the same PR.

Change type	Update
New user-facing feature	docs/tax/ or docs/law/
Architecture change	docs/guide/overview.md
Auth / DB / Firestore change	docs/guide/auth.md
New API endpoint or contract change	docs/guide/api.md
New / removed test categories	docs/guide/testing.md
ROLE_RANK change	docs/guide/auth.md + butler-tax/CLAUDE.md
New repository-wide rule	butlerseries/CLAUDE.md

CLAUDE.md files are read by Claude Code on every session — they should always reflect the current state of the codebase, not an aspirational design.

Branching & PR

Butler Series uses a trunk-based workflow during the pre-release period:

• Commit directly to main
• No long-lived feature branches
• Run all tests locally before pushing
• Group commits by logical concern; the working tree should not contain unrelated mixed changes

PR-style review (when opened) follows:

• Title prefix: [service:tax] / [service:law] / [service:platform]
• Include test results in the description (e.g. "pytest 521 ✅ / playwright 154 ✅")
• Update docs in the same PR as code changes

Commit Message Style

<type>(<service>): <summary in Japanese or English>

<optional body>

Types: feat / fix / refactor / test / chore / docs Services: tax / law / platform / series

Example: refactor(tax): #60 company_profiles を Firestore に移行

Issue Management

All Butler Series issues are tracked in butler-platform: https://github.com/saikoku-studio/butler-platform/issues

Service labels

• service:tax — Butler Tax related
• service:law — Butler Law related
• service:platform — Butler Platform related

Type labels

• type:bug
• type:feature
• type:phase-task — work tied to a release phase
• type:open-question — unresolved design questions

Priority labels

• priority:high / priority:medium / priority:low

Adding a Butler Chat Tool

1. Implement the tool function in backend/app/services/agent_tools.py
2. Add a route in backend/app/api/routes/advisor.py (path uses the bare name, e.g. /tools/approve_document, not exec_*)
3. Update the system prompt in backend/app/services/ai_service.py
4. Add a regression test in tests/test_agent_tools_*.py
5. Add an E2E test in frontend/e2e/chat_actions.spec.ts
6. Update API Reference and Butler Chat

Adding an E2E Test

1. Use the next available numeric ID within the spec file's prefix (APPR-13, CHAT-14, etc.)
2. Stub all /api/v1/** endpoints via page.route()
3. Reuse helpers/auth.ts and helpers/noise.ts for setup
4. If your test interacts with the page underneath the chat overlay, inject CSS to hide .overlay-root in addInitScript

Anti-Patterns to Avoid

• Hard-coding mock data outside helpers/ — keep fixtures shared
• Duplicating route logic across routes/*.py — extract to services/
• Touching MongoDB collections directly from a route — go through the relevant services/ module
• Adding new flags / env vars without docs — update docs/guide/setup.md