gherkin-to-code

Gherkin to Code — Feature Implementation

Đọc Gherkin feature file từ living docs → phân tích technical solution → gen step definitions + implementation code. Skill này là bridge từ WHAT (feature file) sang HOW (code).

Triết lý

Feature file là contract. Code phải thỏa mãn contract đó — không hơn, không kém.

Skill này KHÔNG quyết định stack, framework, hay conventions — đó là việc của CLAUDE.md và existing code trong repo. Skill này chỉ hướng dẫn process: đọc gì → phân tích gì → gen gì → verify gì.

Ngôn ngữ

• Code comments, commit messages: theo convention repo (CLAUDE.md)
• Technical solution summary: tiếng Việt (consistent với PRD và feature file)
• Code: theo ngôn ngữ lập trình của repo

---

Phase 1 — Technical Analysis (bắt buộc, engineer review trước khi code)

Phase này là bước architecture cho feature-level. KHÔNG skip — gen code mà không có technical analysis sẽ dẫn tới refactor.

1.1. Đọc và hiểu feature file

Input: .feature file (hoặc nhiều files nếu feature span nhiều module)

Extract:
├── Feature name + narrative → hiểu context
├── Rules → list business rules cần implement
├── Scenarios per Rule → behaviors cần thỏa mãn
├── Tags → test layer (@api/@web/@integration), priority (@p2/@future)
├── # PRD link → đọc PRD nếu cần thêm context
└── # TODO comments → decisions chưa resolve

1.2. Scan codebase hiện tại

Đọc repo qua git submodule hoặc trực tiếp:

Scan:
├── CLAUDE.md → stack, conventions, patterns
├── Existing step definitions → pattern đang dùng
├── Domain models / entities → data model hiện tại
├── API routes / controllers → endpoints hiện có
├── Database schema → tables, relationships
└── Related features code → follow existing patterns

1.3. Đề xuất Technical Solution

Output dạng summary để engineer review:

## Technical Solution: [Feature Name]

### Tổng quan
[1-2 câu: approach chính để implement feature này]

### Components cần thay đổi

| Component | Thay đổi | Lý do (Rule ID) | Impact |
|-----------|----------|-----------------|--------|
| [service/module] | [new/modify/extend] | [BR-Mxx] | [low/medium/high] |

### Data model changes
| Entity | Thay đổi | Fields | Migration? |
|--------|----------|--------|-----------|
| [entity] | [new table / add columns / modify] | [field list] | [yes/no] |

### API changes
| Endpoint | Method | Thay đổi | Guards (Rules) |
|----------|--------|----------|---------------|
| [path] | [GET/POST/...] | [new/modify] | [BR-Mxx] |

### Quyết định kỹ thuật
- [Decision 1]: [option chọn] — *lý do: [ngắn gọn]*
- [Decision 2]: [option chọn] — *lý do: [ngắn gọn]*

### Breaking changes
- [ ] [Mô tả breaking change nếu có] → *ảnh hưởng: [ai/service nào]*

### Implementation order
1. [Component/step đầu tiên] — *vì: [dependency reason]*
2. [Component/step tiếp theo]
3. ...

Sau khi output Technical Solution → DỪNG LẠI, hỏi engineer:

"Technical solution trên có ok không? Cần adjust gì trước khi gen code?"

Chỉ tiếp Phase 2 sau khi engineer confirm.

1.4. Lưu Technical Solution (optional)

Nếu engineer muốn lưu, ghi vào living docs:

features/[module]/[feature-name].solution.md

Hoặc ghi tóm tắt trong feature file:

# Solution: [1 dòng tóm tắt approach]
# Components: [list services/modules affected]
# Decision: [key technical decision]

---

Phase 2 — Step Definitions (test glue code)

2.1. Nguyên tắc gen step definitions

Follow existing patterns TRƯỚC:

• Scan thư mục step definitions hiện có
• Reuse step đã có nếu match (ví dụ: Given Minh có gói trả phí đang active có thể đã có)
• Follow naming convention, file organization của repo
• Chỉ tạo step mới cho behavior chưa có

Mapping Gherkin → Step:

Gherkin step                    → Step definition làm gì
─────────────────────────────────────────────────────────
Given [trạng thái]              → Setup test data / fixtures
  Given Minh có gói trả phí    → Create merchant + active subscription
  Given Minh có đơn hàng       → Create order with status completed

When [hành động]                → Call API / service method / UI action
  When Minh yêu cầu xuất       → POST /invoices hoặc service.createInvoice()

Then [kết quả]                  → Assert response / state / side-effect
  Then hóa đơn được tạo        → Assert invoice exists, status = Draft
  Then hệ thống từ chối        → Assert error response, no invoice created

2.2. Step definition theo test layer

Dựa trên tag trong feature file:

@api scenarios:

Given → DB setup / API setup calls
When  → HTTP request (REST client)
Then  → Assert HTTP response + DB state

@web scenarios:

Given → DB setup + navigate to page
When  → Browser interaction (Playwright/Selenium)
Then  → Assert page content / UI state

@integration scenarios:

Given → Setup across multiple services
When  → Trigger in service A
Then  → Assert observable in service B

2.3. Output

• Step definition files theo convention repo
• Reuse existing steps khi có thể
• Comments reference Rule ID: // BR-M01: Chỉ merchant active mới được xuất

---

Phase 3 — Implementation Code (business logic)

3.1. Implementation theo Rules

Mỗi Business Rule trong feature file → code cụ thể:

Rule type               → Code pattern
─────────────────────────────────────────
Permission/Guard        → Middleware / guard clause / policy
Validation              → Validator class / validation function
State transition        → State machine / status update logic
Calculation             → Pure function / service method
Side-effect/Notification → Event handler / background job
Uniqueness/Conflict     → DB constraint + application check
Default/Auto-fill       → Factory / builder / mapper
Time-bound              → Scheduler / expiry check
Cascade/Dependency      → Transaction / saga / event chain

3.2. Implementation order

1. Data model changes (migration nếu cần)
   → Entities, DB schema

2. Core business logic (Rules - Must Have trước)
   → Validation, calculation, state machine

3. API layer (endpoints, controllers)
   → Route, request/response mapping

4. Side-effects (notifications, integrations)
   → Event handlers, background jobs

5. Should Have rules (@p2)
   → Sau khi Must Have green

6. Skip @future/@p3
   → Chỉ có feature file làm documentation

3.3. Nguyên tắc gen code

• Follow existing patterns — đọc code hiện có, follow conventions
• Mỗi Rule = testable unit — code phải tổ chức sao cho mỗi rule test được độc lập
• Exception handling từ feature file — cột Exception trong Business Rules table → error responses
• Không over-engineer — chỉ implement đúng những gì feature file yêu cầu
• Commit message reference — feat(billing): implement invoice submission [BR-M01, BR-M02]

---

Phase 4 — Verify

4.1. Run tests

Chạy step definitions với feature file:
├── Must Have scenarios → PHẢI green
├── Should Have (@p2) → NÊN green
├── @future/@p3 → Skip (pending)
└── @wip → Expected fail ok

4.2. Checklist trước khi done

• Mọi Must Have Rule có code implement tương ứng
• Mọi Must Have Scenario chạy green
• Exception paths (error scenarios) xử lý đúng
• Code follow existing patterns trong repo (check CLAUDE.md)
• Không có code cho business rule KHÔNG có trong feature file
• Data model changes có migration
• Breaking changes (nếu có) đã communicate
• Step definitions reuse existing steps khi có thể
• Commit messages reference Rule IDs

4.3. Nếu test fail

Test fail → Đọc scenario lại:
├── Given sai? → Fix test data setup
├── When sai? → Fix API call / action
├── Then sai? → Bug trong implementation HOẶC scenario không chính xác
│   ├── Implementation bug → fix code
│   └── Scenario không chính xác → flag cho Product review
└── Không rõ → đọc PRD (link trong feature file header)

---

Ví dụ thực tế: Engineer prompt → Output

Engineer prompt:

Implement feature từ features/billing/invoice-submission.feature

Claude Code sẽ:

Phase 1: Technical Analysis
├── Đọc invoice-submission.feature
│   ├── 4 Rules: BR-M01 (permission), BR-M02 (calculation), BR-S01 (form), BR-S02 (notification)
│   ├── 7 Scenarios: 4 @api, 2 @web, 1 @future
│   └── PRD link: https://confluence.../pages/123
├── Scan repo
│   ├── CLAUDE.md: .NET 8, Clean Architecture, EF Core
│   ├── Existing: OrderController, InvoiceEntity (chưa có submit logic)
│   └── Step defs: 12 existing steps trong billing/
├── Output Technical Solution
│   ├── New: InvoiceSubmissionService
│   ├── Modify: InvoiceController (add POST /invoices)
│   ├── New: SubscriptionGuard middleware
│   ├── DB: add column Invoice.SubmittedAt, Invoice.ReferenceNumber
│   └── No breaking changes
└── → HỎI ENGINEER CONFIRM

Phase 2: Step Definitions
├── Reuse: 3 existing steps (merchant setup, order setup, login)
├── New: 4 steps (submit invoice, check status, check error, check total)
└── Files: steps/billing/invoice-submission.steps.cs

Phase 3: Implementation
├── 1. Migration: AddInvoiceSubmissionColumns
├── 2. InvoiceSubmissionService (BR-M01 guard, BR-M02 calc)
├── 3. InvoiceController.Submit() endpoint
├── 4. Skip BR-S02 (@future)
└── Run tests → 6/6 green (1 @future skipped)

---

Reference Files

• references/step-patterns.md — Common step definition patterns theo test layer (@api, @web, @integration)