# LLM Agent Instructions

This document contains instructions and documentation references for AI assistants working with this codebase.

> **📖 Important**: Before working on this project, read [PHILOSOPHY.md](PHILOSOPHY.md) to understand the system vision, architectural patterns, and design goals. All development should work towards realizing those patterns.
# AGENTS.md

> **Start every session by reading this file.**
> This file outlines the operational protocols, coding standards, and architectural decisions for this FastAPI project.

## 1. Agent Operational Protocols

### 🧠 Work Patterns (Plan-Act-Reflect)
* **Plan:** Before writing code, briefly outline your plan. Identify which files you will touch and what the side effects might be.
* **Act:** Execute the changes in small, atomic steps.
* **Reflect:** After coding, verify your work. Did you break existing tests? Did you add new tests?

### 🛡️ Git Discipline
* **NEVER commit to `main` or `master` directly.** Always create a feature branch: `feature/your-feature-name` or `fix/issue-description`.
* **Commit Messages:** Use the [Conventional Commits](https://www.conventionalcommits.org/) format.
    * `feat: add user login endpoint`
    * `fix: resolve database connection timeout`
    * `refactor: split monolith dependency file`
* **Atomic Commits:** Keep commits small. One logical change = one commit.

### 📝 Changelog Maintenance
* **Update `CHANGELOG.md`** with every user-facing change.
* Format: `## [Unreleased] - YYYY-MM-DD` followed by `### Added`, `### Changed`, or `### Fixed`.

---

## 2. FastAPI Architecture & Best Practices
*Reference: [FastAPI Best Practices](https://github.com/zhanymkanov/fastapi-best-practices)*

### 📂 Project Structure (Directory-based, NOT File-type based)
Do **not** group files by type (e.g., one huge `routers` folder). Group by **domain/module** inside a `src/` directory.

**Correct Structure:**
```text
src/
├── auth/
│   ├── router.py      # Endpoints
│   ├── schemas.py     # Pydantic models
│   ├── service.py     # Business logic (CRUD, etc.)
│   ├── dependencies.py# Module-specific dependencies
│   └── config.py      # Module-specific settings
├── posts/
│   ├── router.py
│   └── ...
└── main.py            # App entry point