Studi Kasus Spec Kit: CRUD API Golang End-to-End dari Constitution ke Merge

1specify feature category-management

 11. Describe in 2-3 sentences:
 2> Admin-facing API to manage product categories on Santekno Shop.
 3> Customer-facing API to list available categories for filtering.
 4> Categories are used to group products in the catalog.
 5
 62. Who uses it?
 7> Admin: Full CRUD
 8> Customer: Read-only (list only)
 9> Product Service: References category_id in products
10
113. Must be able to:
12> Admin: Create category (name, description, slug)
13> Admin: Update category details
14> Admin: Soft delete category (if no active products)
15> Admin: List all categories (including inactive ones)
16> Customer: List active categories
17
184. Must NOT happen:
19> Delete category that has active products
20> Duplicate category names
21> Customer accessing admin-only endpoints
22
235. Business rules:
24> Category name: 2-100 chars, unique across all categories
25> Slug: URL-safe, auto-generated from name
26> Soft delete: marks inactive, products remain linked
27> Cascade: If parent category deleted, children become root-level

1specify clarify category-management

 1Q1: Hierarchical categories?
 2> No. Flat structure only for Phase 1. Hierarchy tracked: SHOP-457.
 3
 4Q2: What if same name but different case ("Electronics" vs "electronics")?
 5> Case-insensitive unique check. "Electronics" and "electronics" are duplicates.
 6
 7Q3: Slug generation rule?
 8> Lowercase, spaces→dashes, remove special chars. "Smart Phones" → "smart-phones"
 9
10Q4: What happens to products when category is soft-deleted?
11> Products keep their category_id reference. They become "uncategorized" in UI.
12> No cascade change to products.

1specify plan category-management

 1Files to CREATE:
 2- internal/category/domain/entity.go
 3- internal/category/domain/errors.go
 4- internal/category/usecase/interface.go
 5- internal/category/usecase/dto.go
 6- internal/category/usecase/category_usecase.go
 7- internal/category/usecase/category_usecase_test.go
 8- internal/category/repository/postgres_repository.go
 9- internal/category/handler/http_handler.go
10- internal/category/handler/http_handler_test.go
11
12Files to CREATE (infrastructure):
13- migrations/20250703001_create_categories.sql
14
15Files to MODIFY:
16- internal/delivery/http/router/router.go

 1CREATE TABLE categories (
 2    id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
 3    name        VARCHAR(100) NOT NULL,
 4    slug        VARCHAR(120) NOT NULL UNIQUE,
 5    description TEXT,
 6    is_active   BOOLEAN NOT NULL DEFAULT true,
 7    created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
 8    updated_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
 9    deleted_at  TIMESTAMPTZ
10);
11
12CREATE UNIQUE INDEX idx_categories_name_ci
13ON categories(LOWER(name)) WHERE deleted_at IS NULL;

1# Tambahkan instruksi: slug harus generated otomatis, bukan dari input
2specify plan category-management --add-instruction "Slug must be auto-generated from name, NOT user input. User provides name only."
3# Plan di-update

1specify tasks category-management

 1Phase 1: Domain + Migration [2h]
 2  Task 1.1: Create categories migration [30 min]
 3  Task 1.2: Create Category entity [30 min]
 4  Task 1.3: Create domain errors [20 min]
 5  Task 1.4: Create DTOs [30 min]
 6
 7Phase 2: Repository [2h]
 8  Task 2.1: Create repository interface [20 min]
 9  Task 2.2: Implement all CRUD methods [90 min]
10
11Phase 3: UseCase [2h]
12  Task 3.1: Implement usecase [60 min]
13  Task 3.2: Write usecase tests [60 min]
14
15Phase 4: Handler + Integration [2h]
16  Task 4.1: Implement HTTP handler [60 min]
17  Task 4.2: Write handler tests [45 min]
18  Task 4.3: Register routes [15 min]
19  Task 4.4: Wire dependencies [20 min]

 1git checkout -b spec/SHOP-456-category-management
 2git add .specify/features/category-management/
 3git commit -m "spec(SHOP-456): add category management specification
 4
 5Spec: .specify/features/category-management/spec.md (v1.1 after clarify)
 6Plan: .specify/features/category-management/plan.md
 7Tasks: .specify/features/category-management/tasks.md (12 tasks, ~8h estimated)"
 8
 9git push origin spec/SHOP-456-category-management
10# PR dibuat → review by @budi → approved 30 min kemudian

1git checkout -b feat/SHOP-456-category-management develop

1specify implement category-management --phase=1 --verbose

 1[10:21:00] Phase 1 started
 2[10:21:00] Task 1.1: Create categories migration...
 3[10:21:16] ✓ migrations/20250703001_create_categories.sql created
 4[10:21:16] Running: psql $LOCAL_DB_URL -f migrations/20250703001_create_categories.sql
 5[10:21:18] ✓ Migration applied locally
 6
 7[10:21:18] Task 1.2: Create Category entity...
 8[10:21:28] ✓ internal/category/domain/entity.go created (67 lines)
 9
10[10:21:28] Task 1.3: Create domain errors...
11[10:21:37] ✓ internal/category/domain/errors.go created (32 lines)
12
13[10:21:37] Task 1.4: Create DTOs...
14[10:21:52] ✓ internal/category/usecase/dto.go created (78 lines)
15
16[10:21:52] Running post_implement: go build ./...
17[10:21:55] ✓ Build OK

 1// internal/category/domain/entity.go — diperiksa @citra
 2
 3type Category struct {
 4    ID          uuid.UUID  `json:"id"`
 5    Name        string     `json:"name"`
 6    Slug        string     `json:"slug"`
 7    Description *string    `json:"description,omitempty"`
 8    IsActive    bool       `json:"is_active"`
 9    CreatedAt   time.Time  `json:"created_at"`
10    UpdatedAt   time.Time  `json:"updated_at"`
11    DeletedAt   *time.Time `json:"-"`
12}
13
14// ✅ Struktur sesuai plan
15// ✅ DeletedAt untuk soft delete
16// ✅ IsActive boolean (bukan status string)

1# Review OK, commit Phase 1
2git add .
3git commit -m "feat(category): add domain layer and migration [SHOP-456 Phase 1]
4
5- Category entity with soft delete support
6- Domain errors: ErrCategoryNotFound, ErrCategoryNameExists, ErrCategoryHasProducts
7- DTOs: CreateCategoryInput, UpdateCategoryInput, CategoryResponse
8- Migration: idx_categories_name_ci (case-insensitive unique)"

1specify implement category-management --phase=2

 1// SoftDelete — sesuai dengan business rule "tidak boleh delete jika ada produk"
 2func (r *postgresCategoryRepository) SoftDelete(ctx context.Context, id uuid.UUID) error {
 3    // Check apakah ada active products
 4    var productCount int
 5    err := r.db.QueryRow(ctx,
 6        `SELECT COUNT(*) FROM products WHERE category_id = $1 AND status = 'ACTIVE' AND deleted_at IS NULL`,
 7        id).Scan(&productCount)
 8    if err != nil {
 9        return fmt.Errorf("SoftDelete: check products: %w", err)
10    }
11    if productCount > 0 {
12        return domain.ErrCategoryHasProducts
13    }
14
15    // Soft delete
16    result, err := r.db.Exec(ctx,
17        `UPDATE categories SET deleted_at = NOW(), updated_at = NOW() WHERE id = $1 AND deleted_at IS NULL`,
18        id)
19    if err != nil {
20        return fmt.Errorf("SoftDelete: exec: %w", err)
21    }
22    if result.RowsAffected() == 0 {
23        return domain.ErrCategoryNotFound
24    }
25    return nil
26}

 1// Fix: wrap dalam transaction dengan FOR UPDATE
 2func (r *postgresCategoryRepository) SoftDelete(ctx context.Context, id uuid.UUID) error {
 3    tx, err := r.db.Begin(ctx)
 4    if err != nil {
 5        return fmt.Errorf("SoftDelete: begin tx: %w", err)
 6    }
 7    defer tx.Rollback(ctx)
 8
 9    // Lock category row
10    var productCount int
11    err = tx.QueryRow(ctx,
12        `SELECT COUNT(*) FROM products WHERE category_id = $1 AND status = 'ACTIVE' AND deleted_at IS NULL
13         -- Lock products check via NOWAIT to avoid deadlock`,
14        id).Scan(&productCount)
15    // ... rest of logic in transaction
16}

 1# Edit manual, run test
 2go test ./internal/category/repository/...
 3# ✅ PASS
 4
 5git add .
 6git commit -m "feat(category): add repository with race condition fix [SHOP-456 Phase 2]
 7
 8Race condition fix: SoftDelete now uses transaction to prevent
 9concurrent product creation + category deletion race.
10Ref: clarification Q4 (product-category relationship)"

1specify implement category-management --phase=3
2specify implement category-management --phase=4

1specify validate --feature=category-management

 1✅ Spec Compliance Report: category-management
 2
 3AC Coverage:
 4✅ AC1: Admin list all categories — TestListAllCategories_AdminRole
 5✅ AC2: Customer list active only — TestListCategories_CustomerRole_ActiveOnly
 6✅ AC3: Create with unique name — TestCreateCategory_Success
 7✅ AC4: Reject duplicate name (case-insensitive) — TestCreateCategory_DuplicateName
 8✅ AC5: Auto-generate slug — TestCreateCategory_SlugGenerated
 9✅ AC6: Update category — TestUpdateCategory_Success
10✅ AC7: Soft delete — TestSoftDeleteCategory_Success
11✅ AC8: Prevent delete with active products — TestSoftDeleteCategory_HasProducts
12✅ AC9: Customer cannot access admin endpoints — TestAdminEndpoints_CustomerForbidden
13
14Coverage: 91.3% (usecase), 87.2% (repository)
15All ACs covered. No spec drift detected.

 1## Category Management CRUD API — SHOP-456
 2
 3### Spec Compliance
 4All 9 ACs from spec.md covered. See .specify/features/category-management/spec.md v1.1
 5
 6### Key Decisions (from clarifications)
 7- Slug: auto-generated from name (user never sets slug directly)
 8- Unique check: case-insensitive (idx_categories_name_ci)
 9- Delete protection: transaction-based race condition prevention
10
11### Race Condition Fix
12SoftDelete uses transaction to prevent race between product count check
13and actual delete. This was not in the original plan — discovered during impl.
14plan.md updated to reflect this.
15
16### Test Coverage
17- UseCase: 91.3%
18- Repository: 87.2%
19- Handler: 83.6%
20All above 85% target per constitution.

1✅ Spec compliance: semua AC ter-cover
2✅ Architecture: Clean Architecture diikuti
3✅ Race condition fix: good catch!
4💬 Suggestion: Add index on category_id in products table
5    (for performance of "has active products?" check)

 1Total waktu: ~5.5 jam aktual (dari 8h estimate)
 2
 3Breakdown:
 4- Spec (feature + clarify): 25 menit
 5- Plan + tasks: 30 menit (termasuk 1 correction)
 6- Phase 1: 25 menit (implement + review + commit)
 7- Phase 2: 90 menit (implement + race condition fix + test)
 8- Phase 3: 80 menit (implement + review + commit)
 9- Phase 4: 60 menit (implement + review + commit + route)
10- PR + review: 45 menit
11
12Coverage akhir: 87-91% per layer
13Spec compliance: 9/9 ACs
14Bugs found dalam review: 1 (race condition — caught sebelum merge)

 1Tanpa Spec Kit (estimated):
 2- Define requirements di slack: 1h (tidak terdokumentasi)
 3- Implement trial-and-error: 4h
 4- Review: 2h (banyak pertanyaan tentang behavior)
 5- Fix review comments: 1h
 6- Total: ~8h + tidak ada dokumentasi permanen
 7
 8Dengan Spec Kit:
 9- Spec + clarify + plan: 55 menit (semua terdokumentasi)
10- Implement + review: 4.5h (focused, ada roadmap)
11- PR review: 45 menit (reviewer punya spec sebagai reference)
12- Total: 5.5h + full dokumentasi di .specify/

 1.specify/features/category-management/
 2├── spec.md (v1.1) — 89 baris, approved
 3├── clarifications.md — 24 baris
 4├── plan.md — 156 baris
 5└── tasks.md — 98 baris (semua [x])
 6
 7internal/category/
 8├── domain/entity.go — 67 baris
 9├── domain/errors.go — 32 baris
10├── usecase/interface.go — 45 baris
11├── usecase/dto.go — 78 baris
12├── usecase/category_usecase.go — 134 baris
13├── usecase/category_usecase_test.go — 187 baris
14├── repository/postgres_repository.go — 213 baris
15└── handler/http_handler.go — 156 baris
16
17migrations/
18└── 20250703001_create_categories.sql — 18 baris
19
20Total: ~1,077 baris Go + SQL yang di-produce dalam 5.5 jam

 1# Template script: scripts/new-feature.sh
 2#!/bin/bash
 3FEATURE=$1
 4TICKET=$2
 5
 6echo "🚀 Starting Spec Kit workflow for $FEATURE ($TICKET)"
 7
 8# Step 1: Spec branch
 9git checkout -b spec/${TICKET}-${FEATURE} develop
10specify feature $FEATURE
11specify clarify $FEATURE
12specify plan $FEATURE
13specify tasks $FEATURE
14
15# Step 2: Commit spec
16git add .specify/features/${FEATURE}/
17git commit -m "spec(${TICKET}): add ${FEATURE} specification"
18echo "✅ Spec ready. Create PR, get approval, then run:"
19echo "   git checkout -b feat/${TICKET}-${FEATURE} develop"
20echo "   specify implement ${FEATURE} --phase=1"

 1# Update spec dengan fitur baru
 2specify feature category-management --add-ac "AC10: Category can have an icon image URL"
 3
 4# Clarify jika perlu
 5specify clarify category-management --questions="Regarding AC10 only"
 6
 7# Regenerate plan dengan perubahan
 8specify plan category-management --regenerate --scope="AC10 only"
 9
10# Tasks untuk AC10 saja
11specify tasks category-management --scope="AC10"

 1What worked:
 2✅ specify clarify menemukan case-insensitive unique yang terlewat
 3✅ Race condition fix sebelum production (bukan setelah)
 4✅ PR review jauh lebih focused — reviewer punya spec sebagai guide
 5✅ 5.5h vs 8h estimate — lebih efisien dari perkiraan
 6
 7What could be better:
 8⚠️ Plan tidak menyebutkan race condition risk — perlu ditambahkan ke constitution
 9    sebagai "Always use transaction for check-then-act patterns"
10⚠️ Index untuk products.category_id ditemukan saat review, bukan saat plan
11    — perlu ditambahkan ke plan template
12
13Actions:
141. Update constitution: add "check-then-act requires transaction" rule
152. Update plan template: add "check dependent table indexes" section