AI Generation Rules

AI Generation Rules

GherkinForge ships two .cursor/rules/ files that constrain AI coding agents operating inside the framework.

---

bdd-generation.mdc — FAANG-Grade Generation Rules

Applies to all .feature, domain/, usecases/, and adapters/ files.

Why affirmative constraints?

LLMs place heavy mathematical attention on tokens they are told to avoid. Telling an AI "do not use database/sql" increases the probability it hallucinates that import. GherkinForge rewrites every rule as a positive, inescapable command — focusing AI attention on the desired outcome rather than the forbidden behaviour.

Negation (avoided)	Affirmative (used instead)
"Never import database/sql"	"Restrict imports exclusively to stdlib primitives"
"Never call time.Now()"	"Retrieve time exclusively via injected Clock interface"
"Never use time.Sleep()"	"Synchronise exclusively using channels or sync.WaitGroup"
"Never use global variables"	"Isolate state exclusively through context.WithValue"

The six rule sections

1. Architectural Boundaries — domain isolation, rich domain models, accept-interfaces-return-structs
2. FAANG Go Idioms — ctx propagation with Done() cancellation, %w error wrapping, sync.Mutex, pointer/value semantics, int64 precision table
3. Resilience — constructor DI, Clock interface with fixedClock + wallClock implementations
4. BDD State Management — context.WithValue scenario state, channel waits, hard fmt.Errorf assertions
5. Generation Sequence — 7-step outside-in TDD order (spec → domain → usecases → adapters → fakes → step defs → GREEN)
6. Zero Trust Checklist — 10-point self-verify gate the AI must pass before declaring complete

---

translate-legacy-gherkin.mdc — Translation Engine

Converts legacy imperative Gherkin into dual-audience declarative format.

Usage in Cursor

1. Open a legacy .feature file
2. Ctrl+A → Ctrl+K
3. Type: Refactor this using the translate-legacy-gherkin rules

Seven translation rules

Rule	Transform
1 — Tier tagging	Add @business, @integration, or @nfr
2 — Purge incidental detail	I click Submit → the customer submits an order
3 — Force DataTables	Prose lists → typed | column | headers |
4 — Force DocStrings	JSON payloads → """json ... """
5 — Event assertions	Every Then gets a domain event + mathematical invariant
6 — Background extraction	Repeated Given steps → single Background: DataTable
7 — Outcome naming	Scenario: click submit → Scenario: order emits domain event

Validation checklist (pre-output gate)

The Translation Engine self-verifies against 8 criteria before outputting — including zero banned UI words, int64 pence throughout, domain events on every write scenario, and a mathematical invariant on every Then.

---

Installing Rules in Your Project

# Copy both rules into your project
cp .cursor/rules/bdd-generation.mdc your-project/.cursor/rules/
cp .cursor/rules/translate-legacy-gherkin.mdc your-project/.cursor/rules/

Or reference them directly from the GherkinForge repo in your own .mdc files.