backend-go
Expertise in developing and maintaining the Go backend with Clean Architecture.
SKILL.mdtemplates/antigravity/go/.agents/skills/backend_go/SKILL.md
GitHubBackend (Go) Development Skill
Main Instructions
When working on the Go backend (apps/backend/), you MUST follow these instructions:
1. Before Writing Any Code
- Read
docs/clean-architecture.mdto understand the layered architecture. - Identify which layer(s) the change belongs to:
- Entities (
internal/entity/): Core domain structs, no external dependencies. - Services (
internal/service/): Business logic, defines repository interfaces. - Delivery (
internal/delivery/http/): HTTP handlers, request parsing, response formatting. - Middleware (
internal/middleware/): Cross-cutting concerns (auth, CORS, logging). - Repository (
internal/repository/postgres/): SQL queries, implements service interfaces.
- Entities (
2. Dependency Rule (NEVER Violate)
- Dependencies MUST only point inwards:
Delivery -> Service -> Entity. Repositoryimplements interfaces defined inService.- Inner layers (Entity, Service) must NEVER import outer layers (Delivery, Repository).
3. When Adding a New Endpoint
- Define the Entity/Request/Response structs in
internal/entity/. - Add the method signature to the Service interface in
internal/service/. - Implement the business logic in the Service.
- Add any necessary Repository interface methods and their PostgreSQL implementations.
- Create the HTTP Handler in
internal/delivery/http/and register the route. - Add or update the OpenAPI spec in
apps/backend/openapi.yaml.
4. When Modifying Existing Code
- Check which layer the change belongs to.
- Ensure changes do not introduce cross-layer dependencies that violate the dependency rule.
- Update related tests.
5. Coding Standards
- Use idiomatic Go error handling (
if err != nil). Wrap errors with context. - Ensure all public entity structs have proper
jsontags. - Use
.envfor local configuration; NEVER hardcode secrets or commit.env. - Write unit tests for Services using Mock Repositories.
6. Database Changes
- Place migration SQL files in
migrations/(use naming:NNN_description.up.sql/.down.sql). - Place seed data in
seed/. - Apply with
make db-migrate, seed withmake db-seed, or full reset withmake db-reset.
7. Running & Testing
- Start the server:
make backend-run(from root) orgo run cmd/main.go(fromapps/backend). - Run tests:
make backend-testorgo test ./...fromapps/backend.
Reference Examples
- examples/endpoint_reference.md: Full end-to-end guide for adding a new endpoint (Entity → Service → Repo → Handler → Route), based on the actual Task implementation.