develop-repository

Implements Go persistence-layer repositories and query services through a TDD cycle against real PostgreSQL.

Updated Sep 14, 2026
One-click install
npx skills add https://github.com/nakamori-naoya/go-convention-plugins --skill develop-repository-nakamori-naoya
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: develop-repository
Source: https://github.com/nakamori-naoya/go-convention-plugins/tree/main/plugins/go-convention/skills/develop-repository
Command: npx skills add https://github.com/nakamori-naoya/go-convention-plugins --skill develop-repository-nakamori-naoya

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Building a Go persistence layer (a repository for one aggregate or a query service for one read contract) requires coordinating tests, implementation, and conventions in the right order. This Skill orchestrates one complete TDD cycle—write failing tests against a real PostgreSQL database, verify red, implement, verify green, then refactor—while delegating the actual test and implementation rules to dedicated convention skills. ## Core Features & Use Cases - Orchestrated TDD cycle: Runs a fixed playbook (fix-unit → write-failing-test → run-red → implement → run-green → refactor → align-errors → report) where the same agent executes each step in declared order. - Dual unit kinds: Handles either one aggregate's Repository interface implementation (standard or event-sourced) or one read contract's query service implementation, dispatching to the matching implementation convention. - Real-database testing: Tests run against actual PostgreSQL via dockertest with pgx/v5, sqlc, and testify, mapping BDD scenarios from data-model documents into table-driven tests with Seed/Read helpers. - Use Case: Given a data-model document with BDD Before/After scenarios for a reservation aggregate, ask the agent to implement its repository via TDD; it writes failing tests first, confirms red, implements the marshaller and sqlc queries, confirms green, and aligns error sentinel translation. ## Quick Start Implement this aggregate's repository with TDD using the BDD scenarios from the attached data-model document, writing the failing tests first.

Frequently Asked Questions about develop-repository

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I implement a Go repository with TDD against a real PostgreSQL database?▼

Write failing tests first using dockertest to spin up real PostgreSQL, verify they fail because the implementation is missing, then implement the repository with sqlc queries and a marshaller until tests pass. This Skill orchestrates that exact cycle for one aggregate at a time.

How to test a sqlc-based repository in Go with dockertest?▼

Use dockertest to launch a PostgreSQL container, apply the DDL, and seed tables with rdbtest Seed helpers before each test case. Tests compare post-operation rows against the BDD document's After state using Read helpers and testify assertions.

Does this workflow support query services as well as repositories?▼

Yes, the fix-unit step classifies the target as either a Repository interface implementation or a query service implementing a usecase-owned read contract. Only the matching implementation convention is invoked for the chosen kind.

What happens when the red test fails for the wrong reason?▼

The run-red step classifies failures, and reasons like missing Docker, mismatched DDL, missing rdbtest helpers, or unrelated test failures do not count as valid red. The workflow stops and reports the cause instead of proceeding to implementation.

What are the prerequisites for using this TDD workflow?▼

You need Go 1.27, PostgreSQL, pgx/v5, sqlc, dockertest, testify, and a running Docker daemon. The domain implementation (aggregates, value objects, Repository interface, sentinels) and the data-model document must already be finalized.

When should database constraint violations be translated to sentinel errors?▼

Translation happens in the repository implementation, mapping DB-rejected facts like constraint violations, NotFound, and optimistic-lock conflicts to domain sentinels. The align-errors step runs only when this unit added or changed such translations, ensuring a single translation point with one %w wrap.