OpenParable
Skip to content
← Back to skills

Data Layer Contracts

Development
data-layer-contracts

Data Layer Contracts is an Agent Skill for development published in the Bottelet/DaybydayCRM repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Defines the schema-to-factory-to-seeder contract chain — NOT NULL alignment, factory/seeder ownership boundaries, and schema drift rules

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/Bottelet/DaybydayCRM/blob/HEAD/.claude/skills/data-layer-contracts/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/data-layer-contracts, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Data Layer Contracts

Purpose

Defines the contract chain from migration schema to factory to seeder, and prevents drift between them.


Schema Contract

Every NOT NULL column defined in a migration must be supported by:

  • a factory definition, or
  • a seeder definition (only for seed data), or
  • an explicit DB default in the migration

This is a schema-only rule, not a validation rule. MySQL/MariaDB is the canonical database — SQLite differences are invalid for schema validation assumptions.


Factory Rules

Factories MUST:

  • satisfy all NOT NULL columns
  • reflect migration constraints
  • represent the smallest valid persisted entity — not random data, not business scenarios, only valid schema state

Factories MUST NOT:

  • enforce business rules or validation rules
  • replace service-layer creation logic
  • define seeder logic, or depend on seeders

If a migration introduces a NOT NULL column, the factory MUST be updated immediately — omission is invalid state.

Factories SHOULD align with service-layer expectations but do NOT depend on it: service layer = behavior, factory = valid structure.


Seeder Rules

Seeders MUST:

  • rely on factories for object creation — factories are the source of truth for valid model state
  • orchestrate dependency order between models, optionally via helpers (findOrCreateClient, findOrCreateProject, findOrCreateUser — convenience utilities, not business logic)
  • only insert schema-valid data, with no reliance on implicit database defaults

Seeders MUST NOT:

  • define validation rules, factory structure, or schema constraints
  • contain business logic

Seeders assemble data. They do not define data correctness.


Drift Triggers

The following indicate schema drift: migration changes, factory mismatch, seeder mismatch, SQLSTATE constraint violations, CI vs local DB mismatch.

Schema validation requires migrate:fresh + seed before running test suites.


Identity Rule

Primary keys are non-deterministic. Tests MUST NOT rely on hardcoded IDs.