library-desk/AGENTS.md

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 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

📂 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:

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