Coding Agent Rules and Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
Athena is an osu! bancho-compatible private server implemented as a Python modular monolith. Because the project is optimized for parallel coding-agent work, it enforces strict architectural boundaries, specific development workflows, and high standards for code quality and type safety. The primary goal of these guidelines is to maintain a Pythonic, well-partitioned codebase that remains practical to deploy and scale.
These rules ensure that agents—whether working solo or in parallel—do not violate the project's hexagonal adapter structure or introduce technical debt due to expensive refactoring costs, which are considered "effectively zero" for AI agents.
Sources: README.md:1-11, AGENTS.md:65-72
Architectural Principles
Athena follows a layered modular monolith architecture with hexagonal adapters and a strict command/query use-case split. Agents must adhere to the production dependency direction: composition -> runtime adapters -> command/query use-cases -> repositories -> infrastructure.
Design Philosophy
Design decisions must start from a "blank slate." Implementation cost, diff size, and refactoring effort are never valid reasons to avoid a superior design. Agents are expected to:
- Propose rewrites when existing code is not elegant.
- Prioritize pattern consistency across the entire codebase.
- Avoid "don't touch working code" as a passive excuse.
Sources: AGENTS.md:76-105, README.md:27-33
Layered Boundaries and Constraints
The project uses import-linter to enforce dependency rules. The following table summarizes forbidden dependencies for key layers:
| Layer | Forbidden Imports / Dependencies |
|---|---|
| Domain | Pydantic, SQLAlchemy, Starlette, Repository implementations, Services, Jobs, HTTP clients. |
| Services | Transports, concrete Repository implementations (SQLAlchemy/Memory), Starlette, FastAPI, Taskiq. |
| Repositories (Interfaces) | concrete persistence implementations, Services, Transports, Infrastructure, Jobs. |
| Jobs | Transports, Composition, concrete Repository implementations, Starlette, FastAPI. |
Sources: AGENTS.md:144-162, pyproject.toml:130-220, tests/unit/test_architecture_boundary_contract.py:33-145
Dependency Flow Diagram
The following diagram illustrates the allowed communication paths between architectural layers:
The composition layer acts as the outer root, wiring the runtime graph using Dishka providers. Runtime adapters (e.g., Starlette routes) must remain thin and not import concrete infrastructure.
Sources: AGENTS.md:107-124, README.md:35-46
Development Workflow
Agents must use isolated environments and structured task management to prevent conflicts during parallel development.
Parallel Worktree Management
For any substantive work, agents should use the scripts/agent-worktree.sh utility to create a task-specific git worktree.
- Isolation: Each agent works in its own worktree and agent-prefixed branch (e.g.,
claude-code/<task-slug>). - Environment: Project toolchain commands (e.g.,
uv,pytest,ruff) must be executed withinnix develop. - Integration: Pull requests are the mandatory integration boundary for non-trivial changes. Merges are performed by users via the GitHub Web UI.
Sources: AGENTS.md:247-290, README.md:104-112, CLAUDE.md:13-18
Workflow Logic
Agents must run the local quality gate (./scripts/ci.sh quality) and test gate (./scripts/ci.sh test) before reporting work as complete.
Sources: AGENTS.md:54-58, README.md:79-86, CLAUDE.md:10-18
Code Quality and Documentation
Type Safety and Linting
The project enforces basedpyright strict mode and ruff.
- No Shortcuts: Broad
# type: ignoreor# noqaare prohibited unless structural alternatives are exhausted. - Resolution Path: Fix the code -> Use stubs/Fakes -> Generate stubs -> Inline suppression (last resort with documentation).
- Mocks: Prefer typed in-memory implementations or Protocol-compliant stubs over untyped
AsyncMock.
Sources: AGENTS.md:329-354, tests/README.md:5-24, pyproject.toml:90-110
Python Docstring Standards
Docstrings must follow Google Style and be written in Japanese.
- Requirement: Explain behavior, arguments, return values, exceptions, and constraints.
- Technical Terms: English terms for protocol values or wire fields are acceptable but must be supplemented with Japanese explanations.
- ASCII Punctuation: Use
(),:,/,-to avoid linting issues (RUF002).
Sources: AGENTS.md:314-327
Git Commit Rules
Athena follows the Conventional Commits specification.
- Format:
<type>[optional scope]: <description>(Description in Japanese). - Footers: Agents must include
Agent-Model: <agent product> (<model name>). - Kiro Integration: For sequential tasks, include
Kiro-Task: <spec-name> <task-number>.
Sources: AGENTS.md:374-394
Testing Standards
Testing code must meet the same quality and type-safety standards as production code.
| Testing Pattern | Recommendation |
|---|---|
| External Dependencies | Use InMemory implementations (e.g., InMemoryUserRepository). |
| API Boundaries | Create Typed Fake classes in tests/support/fakes.py. |
| Data Generation | Use Typed Factory functions in tests/factories/. |
| Mocking | Avoid AsyncMock due to Any return types; use Protocol-compliant stubs. |
Sources: tests/README.md:1-30, AGENTS.md:342-345
Summary
The Coding Agent Rules and Guidelines establish a zero-compromise approach to architecture and code quality in the Athena project. By enforcing strict boundary isolation via import-linter, mandatory parallel worktrees, and Japanese-language documentation, the project ensures that AI agents can contribute safely and effectively to a modular Pythonic codebase. Compliance with the project gates (ci.sh) and type-safety protocols is required for all implementation work.
Sources: AGENTS.md:54-58, README.md:104-112, tests/unit/test_architecture_boundary_contract.py:532-540