ai-agents-workspace-starter: Skill for Claude Code

Skill: Add REST Endpoint

Full procedure for adding a new REST endpoint. Hexagonal Architecture (domain -> application -> adapters -> interface).

1. Domain Entity (backend/app/domain/entities.py)

• Pure @dataclass (or Pydantic BaseModel) - zero framework dependencies
• Fields: id: int | None, typed attributes, created_at: datetime | None

2. Domain Port (backend/app/domain/ports.py)

• ABC class with @abstractmethod async methods: get_by_id, save, list_active
• Return domain entities, not ORM models

3. Application Service (backend/app/application/{name}_service.py)

• Constructor accepts repository port via DI
• One public method per use case
• Raises custom exceptions (NotFoundError, ValidationError)
• Returns Pydantic response schema (via model_validate)

4. Pydantic Schemas (backend/app/schemas/{name}.py)

• *Create / *Update for requests, *Response for responses
• Response schema: model_config = {"from_attributes": True}

5. SQLAlchemy Adapter (backend/app/infrastructure/adapters/db/)

• models.py - ORM model with to_entity() / from_entity() methods
• repositories.py - implements port, accepts AsyncSession, uses flush() not commit()

6. FastAPI Router (backend/app/interfaces/api/{name}.py)

• Thin: one service method call per endpoint
• Depends() for service + auth injection
• Explicit response_model and status_code (201 for POST, 204 for DELETE)

7. Alembic Migration

make db-migrate msg="add {table} table"
make db-upgrade

8. Tests

make test

---

See also (MANDATORY)

• Before implementation - read workflows/spec-development.md
• Migrations - if new model, read skills/database-migration.md
• Tests - read skills/write-python-tests.md
• After implementation - run workflows/post-impl-verify.md