♻️ refactor(docs): restructure CLAUDE.md with modular rules

[itisnotyourenv]

Pull Request

Description

Restructure CLAUDE.md using progressive disclosure pattern: compact root file (~63 lines, was ~97) with critical rules always loaded, detailed documentation in .claude/rules/ loaded on demand by context.

Type of Change

• Documentation update
• Code quality improvement

Changes

New: Critical Rules section in CLAUDE.md

IMPORTANT-marked rules that are always loaded:

• Business logic MUST live in Interactors only
• NEVER use repositories directly outside of Interactors
• NEVER pass ORM models to application/domain layers
• NEVER import from infrastructure in domain or application

New: Git Conventions section

• Emoji conventional commits format documented from existing practice

New: .claude/rules/ modular files

File	Content
architecture.md	4-layer Clean Architecture details, directory structure, dependency direction
patterns.md	Value Objects, Interactors, Mappers, DI, i18n with stub generation
testing.md	Setup, pytest config, test structure, factories, fixtures

Simplified sections

• Architecture → 1 line + reference to rules
• Configuration → minimal
• Ruff → minimal

Testing

• No code changes, documentation only
• Pre-commit hooks pass

Code Quality

• I have performed a self-review of my own code
• My changes generate no new warnings
• Pre-commit hooks pass

Additional Notes

Design document: docs/plans/2026-02-25-claude-md-restructuring-design.md

Rules in .claude/rules/ auto-load when Claude works with relevant files, keeping the root CLAUDE.md lean while preserving all documentation.

---

🤖 Generated with Claude Code

[claude]

PR Review: ♻️ refactor(docs): restructure CLAUDE.md with modular rules

Overall Assessment: ✅ Approve (with minor suggestions)

This is a well-executed documentation refactor. The progressive disclosure pattern is a good fit for AI context management — keeping critical architectural constraints always in view while offloading reference material to on-demand rule files. The structure is clean and the rationale is sound.

---

✅ What Works Well

• Critical Rules section is a genuine improvement. Elevating hard architectural constraints (IMPORTANT:-marked) ensures they're never missed regardless of what context is loaded.
• Git Conventions section fills a real gap — the emoji conventional commit format was practiced but undocumented.
• i18n stub generation workflow (just generate-i18n, scripts/generate_i18n_stubs.py) is now properly documented in patterns.md. This was missing from the original.
• .claude/rules/ auto-loading is working as described — all three rule files appear in context when working with the codebase.
• Single well-scoped commit, message follows conventions.

---

⚠️ Suggestions for Improvement

1. Information loss in Ruff section

The old CLAUDE.md included enforcement detail that was useful context:

# Old (removed):
Enforces type annotations (ANN), security checks (S/bandit), import sorting (I).
Tests are exempt from annotation and security rules.

The new version drops to just:

Target: Python 3.13, line length 88. Pre-commit hooks run ruff format + check.

The exemptions for test files and the active rule sets (ANN, S) are worth preserving — they prevent confusion when writing code that passes locally but fails CI. Consider adding these back to CLAUDE.md or a tooling.md rules file.

2. Configuration section lost actionable detail

Old:

Both are gitignored. Copy from config-example.yaml and fill in bot token + credentials.

New just says "copy from config-example.yaml" without the reminder to fill in credentials. For a template repo, this is a common first-time stumbling block worth keeping explicit.

3. Design document placement

docs/plans/2026-02-25-claude-md-restructuring-design.md is well-written, but committing dated design/planning documents to the repo creates a question of long-term maintenance. If this is intentional as an ADR (Architecture Decision Record) pattern, consider renaming to docs/decisions/ or docs/adr/ and using a consistent ADR format. If it was just working notes, it may not need to be committed at all.

---

❓ Questions for Clarification

1. Is the docs/plans/ directory an established pattern in this repo, or is this the first design document? If the latter, it might be worth deciding on a convention before it becomes inconsistent.
2. The architecture.md rules file omits the concrete VO examples (UserId, FirstName, LanguageCode) that were in the original. Was this intentional? Those examples were useful orientation for contributors adding new VOs.

---

No Critical Issues

No bugs, no security concerns, no breaking changes — this is documentation only and the content is accurate and well-organized.