# AI Developer Guide

Version: 1.0

This document defines the engineering standards expected from every AI agent contributing to AI MusiMuse.

This guide complements **SPEC.md**.

If any instruction in this document conflicts with **SPEC.md**, the specification always takes priority.

---
# 0. The AI must never modify

The AI must never modify

SPEC.md

ARCHITECTURE.md

PROJECT_PRINCIPLES.md

AI_DEVELOPER_GUIDE.md

unless explicitly instructed.

If implementation reveals a better design,
describe the proposal,
but never silently modify architectural documentation.

---

# 1. General Philosophy

Your responsibility is not to generate code.

Your responsibility is to build a maintainable research platform.

Always optimize for:

* readability
* simplicity
* determinism
* maintainability
* explainability

Never optimize for writing the smallest amount of code.

Never optimize for cleverness.

Future contributors should immediately understand every design decision.

---

# 2. Think Before Coding

Never start implementing immediately.

Before writing code:

* understand the task
* understand the architecture
* identify dependencies
* identify affected modules
* verify assumptions

If requirements are ambiguous, stop and explain the ambiguity instead of guessing.

Never invent missing requirements.

---

# 3. Follow the Specification

SPEC.md is the source of truth.

Do not change architecture during implementation.

Do not introduce alternative designs unless explicitly requested.

Do not rename concepts defined by the specification.

---

# 4. One Responsibility

Every module should have one clear purpose.

Every class should have one clear purpose.

Every function should perform one logical operation.

If a function performs multiple independent tasks, split it.

---

# 5. File Size

Avoid very large files.

Recommended limits:

* Function: under 40 lines
* Class: under 300 lines
* Module: under 500 lines

These are guidelines, not strict limits.

Readability is more important than exact numbers.

---

# 6. Simplicity

Choose the simplest correct solution.

Avoid unnecessary abstraction.

Avoid unnecessary inheritance.

Avoid unnecessary generics.

Avoid unnecessary design patterns.

The best architecture is usually the one with the fewest moving parts.

---

# 7. Explicit Code

Prefer explicit behavior.

Avoid hidden side effects.

Avoid implicit initialization.

Avoid global mutable state.

Code should be predictable.

---

# 8. Documentation

Every public function requires a Google-style docstring.

Every public class requires documentation.

Every module should begin with a short description.

Document *why*, not only *what*.

---

# 9. Type Hints

All public functions require type hints.

Avoid using `Any` unless absolutely necessary.

Prefer concrete types.

Enable static analysis.

---

# 10. Error Handling

Never ignore exceptions.

Never use empty `except` blocks.

Never suppress errors silently.

Raise meaningful exceptions.

Explain the cause whenever possible.

---

# 11. Logging

Use Structlog.

Never use `print()` for application logic.

Log important events.

Avoid excessive logging.

Sensitive information must never be written to logs.

---

# 12. Configuration

Never hardcode configurable values.

Runtime configuration belongs in Settings.

Algorithm parameters belong in project configuration.

Magic constants are discouraged.

---

# 13. Database

Database access should remain isolated.

Business logic must not depend on SQL queries.

Avoid database-specific assumptions.

Write portable code whenever practical.

---

# 14. Determinism

The same input should always produce the same output.

Avoid hidden randomness.

Randomness must always be explicit and configurable.

---

# 15. Testing

Every new feature should include tests.

Prefer small isolated tests.

Regression tests are mandatory for deterministic algorithms.

Broken tests must never be ignored.

---

# 16. Dependencies

Every dependency must have a reason.

Avoid adding libraries for trivial functionality.

Prefer the Python standard library whenever reasonable.

Keep the dependency graph small.

---

# 17. Performance

Correctness comes first.

Profile before optimizing.

Never sacrifice readability for premature optimization.

Caching should never change results.

---

# 18. Git

One task should produce one logical commit.

Commit messages should describe intent.

Avoid unrelated changes.

Do not reformat unrelated files.

---

# 19. Code Reviews

Before considering work complete, verify:

* Does the implementation follow SPEC.md?
* Is the solution deterministic?
* Is the code understandable?
* Can it be tested?
* Can it be extended?
* Is the public API clean?
* Is documentation complete?

If the answer is "no" to any question, continue improving the implementation.

---

# 20. Architecture

Dependencies always point toward lower layers.

Never create circular imports.

Never allow UI to depend on DSP.

Never allow DSP to depend on AI.

Never allow infrastructure to contain business logic.

Keep layers independent.

---

# 21. AI Behaviour

When implementing a task:

Do not solve future tasks.

Do not anticipate requirements.

Do not implement "just in case" functionality.

Only implement what the current task requires.

Leave clear extension points where appropriate.

---

# 22. Communication

When a task is complete:

Summarize what was implemented.

List important design decisions.

List any assumptions.

List potential improvements.

Do not claim features that were not implemented.

---

# 23. Project Mindset

AI MusiMuse is a long-term project.

Write code that another engineer will enjoy reading five years from now.

Every line of code should make the project simpler, not more complicated.

Whenever uncertain, choose the solution that improves clarity.