Claude-Code-Project-Structure-Learning-Repository: Instructions file for Claude Code

Blog API — Claude Instructions

Project Overview

This is a REST API for managing blog posts, authors, and comments. Built with FastAPI + SQLite. The API supports CRUD operations, pagination, and basic auth.

Tech Stack

• Language: Python 3.11
• Framework: FastAPI
• Database: SQLite (via SQLAlchemy ORM)
• Testing: pytest + httpx
• Linting: ruff, black

Directory Structure

arc/
├── main.py          # FastAPI app entry point
├── database.py      # SQLAlchemy engine + session
├── models.py        # ORM models (Post, Author, Comment)
├── schemas.py       # Pydantic request/response schemas
└── routes/
    ├── posts.py     # /posts endpoints
    ├── authors.py   # /authors endpoints
    └── comments.py  # /comments endpoints

How to Run

pip install -r requirements.txt
uvicorn arc.main:app --reload

How to Test

pytest arc/tests/ -v

Coding Rules (IMPORTANT — always follow these)

1. Never use SELECT * — always name columns explicitly in raw SQL.
2. All routes must have a docstring explaining what they do.
3. Pydantic schemas live in schemas.py — do NOT define inline response models inside route files.
4. All database writes must go through a service function in arc/services/ — routes should not call the ORM directly.
5. Do not add print statements — use the logging module instead.
6. Error responses must use HTTPException with a clear detail message.

Commit Style

Use conventional commits:

• feat: new feature
• fix: bug fix
• refactor: no behaviour change
• test: test-only changes

Things to Avoid

• Do NOT touch arc/migrations/ manually — use Alembic.
• Do NOT commit .env files.
• Do NOT use datetime.now() — use datetime.utcnow() for consistency.