🚀 Delphi AI Spec-Kit

An opinionated ecosystem of rules, skills and steerings to elevate Delphi development to state-of-the-art with Artificial Intelligence.

Sponsorship

Delphi/Lazarus components <www.inovefast.com.br>

Integrations with payment platforms and services (Asaas, MercadoPago, Cielo, PagSeguro, D4sign, Webstore, MelhorEnvio, Groq)

i9DBTools <www.inovefast.com.br/i9dbTools/> Manage MySQL, PostgreSQL, Firebird and SQLite in one place, with AI to generate and explain SQL in natural language, optimize queries and create Brazilian fake data in seconds.

📋 Index

• What is this project?
• Why use?
• Supported AI-Tools
• Main Guidelines
• Supported Frameworks
• Kit Structure
• Quick Start
• Code Examples
• Contributions

---

💡 What is this project?

The Delphi AI Spec-Kit is not a code framework — it's a set of behavior guidelines for your favorite AI. It "teaches" the wizard to write Delphi code:

• ✅ Clean — no god classes, no business logic in OnClick
• ✅ Secure — zero memory leaks with try..finally and (ARC) interfaces
• ✅ Testable — TDD with DUnitX, Fakes via interface, without real bench in tests
• ✅ Architected — SOLID, DDD, Repository/Service Pattern and clean architecture

Say goodbye to AI that mixes database access with the presentation layer, forgets try..finally or ignores Dependency Injection.

---

🤔 Why use it?

Without Spec-Kit	With the Spec-Kit
AI generates code with logic in OnClick	AI isolates layers correctly
TStringList.Create without try..finally	Memory gold standard always applied
Tests coupled to the real bank	Fakes via interface, quick and isolated tests
Inconsistent naming	A-params, F-fields, T-types, verbs in methods
with statement and global variables	Code smells blocked proactively

---

🤖 Supported AI Tools

Tool	Configuration File	How It Works
GitHub Copilot	.github/copilot-instructions.md	Pre-prompt injected into Workspace/Chat
Cursor	.cursor/rules/*.md	Rules loaded by context
Claude Code	.claude/	Rules by context and skills in the terminal
Google Gemini / Antigravity	.gemini/skills/*/SKILL.md	Modular skills by domain
Kiro AI	.kiro/steering/*.md	Stack and architectural constraints
Any AI	AGENTS.md	Universal rules (project root)

---

🌟 Key Guidelines Taught to AI

🧠 Memory Management Zero-Leak

The AI ​​enforces the pattern: every .Create without Owner requires try..finally on the immediately subsequent line. Also teaches the use of Interfaces (ARC) for native Garbage Collection — without Free manual.

//✅ Gold Standard — ALWAYS generated by AI with Spec-Kit
var LList: TStringList;
begin
  LList := TStringList.Create;
  try
    LList.Add('item');
  finally
    LList.Free;
  end;
end;

🧪 TDD with DUnitX

Red-Green-Refactor flow with Fakes isolated per interface. No coupling to the database in tests.

[Test]
procedure ProcessOrder_WithoutStock_RaisesException;
begin
  Assert.WillRaise(
    procedure begin FSut.Process(FEmptyOrder); end,
    EInvalidOrderException
  );
end;

🏛️ SOLID and DDD

• S — One class, one responsibility. TCustomerValidator does not save to the bank.
• O — Extension via interfaces, without modifying existing code.
• L — Inheritance only with a clear contract. Preferred interfaces.
• I — Small and specific interfaces. Avoid giant interfaces.
• D — Dependency injection in the constructor, never hardcoded concrete instances.

//✅ DIP in practice
constructor TOrderService.Create(
  ARepo: IOrderRepository;
  ANotifier: INotificationService);
begin
  FRepo := ARepo;
  FNotifier := ANotifier;
end;

📖 Clean Code — Pascal Guide

Consistent and mandatory nomenclatures:

Category	Convention	Example
Parameters	Prefix A	ACustomerName
Private fields	Prefix F	FCustomerName
Local variables	Prefix L	LCustomer
Classes	Prefix T	TCustomerService
Interfaces	Prefix I	ICustomerRepository
Exceptions	Prefix E	ECustomerNotFound

---

🛠️ Supported Frameworks and Libraries

Framework	Domain	Rules Included
Horse	Minimalist REST APIs	Controller/Service/Repository structure, middleware
Dext Framework	.NET-style APIs, ORM, DI, Async	Minimal APIs, Entity ORM, TAsyncTask.Run
DelphiMVC (DMVC)	REST APIs with Attributes	[MVCPath], Active Record, JWT, RQL
ACBR	Commercial Automation (NFe, CF-e, Boleto)	Tax isolation, without crossing with UI
Intraweb	Stateful WebApps in Delphi	UserSession, no global session variables
DevExpress	Advanced Enterprise UI	TcxGrid, TdxLayoutControl, skins and export
Firebird Database	Corporate Database	FireDAC Connection, PSQL, generators, transactions, migrations
PostgreSQL Database	Modern Database	FireDAC Connection, UPSERT, JSONB, Full-Text Search, PL/pgSQL
MySQL / MariaDB	Popular Database	FireDAC Connection, AUTO_INCREMENT, UPSERT, JSON, FULLTEXT
DUnitX	Unit Tests	Red-Green-Refactor, Fakes via interface
Design Patterns GoF	Design Patterns	Creational, Structural and Behavioral with interfaces and ARC
Threading	Multi-Threading	TThread, TTask, Synchronize/Queue, TCriticalSection, PPL
Code Refactoring	Code Smells and Techniques	Extract Method/Class, Guard Clauses, Strategy, Parameter Object

---

📂 Kit Structure

delphi-spec-kit/
│
├── AGENTS.md                        # 🌐 Universal rules (Copilot, Kiro, Antigravity, Gemini)
│
├── .claude/
│   ├── CLAUDE.md                    # 🧠 Master system prompt for Claude
│   ├── settings.json                # Permission settings
│   ├── commands/
│   │   └── review.md                # Slash-command: /project:review
│   ├── rules/                       # Context-specific rules (auto-loaded by glob)
│   │   ├── delphi-conventions.md    # Naming conventions and code style
│   │   ├── memory-exceptions.md     # Memory management and exception patterns
│   │   ├── tdd-patterns.md          # TDD and DUnitX
│   │   ├── solid-patterns.md        # SOLID and DDD
│   │   ├── design-patterns.md       # Design Patterns GoF (Creational, Structural, Behavioral)
│   │   ├── refactoring.md           # Code refactoring (Extract Method, Guard Clauses, Strategy)
│   │   ├── horse-patterns.md        # Horse REST Framework
│   │   ├── dmvc-patterns.md         # DelphiMVC Framework
│   │   ├── dext-patterns.md         # Dext Framework
│   │   ├── acbr-patterns.md         # Commercial Automation (ACBr)
│   │   ├── intraweb-patterns.md     # Intraweb WebApps
│   │   ├── firebird-patterns.md     # Firebird Database (connection, PSQL, transactions)
│   │   ├── postgresql-patterns.md   # PostgreSQL Database (UPSERT, JSONB, FTS)
│   │   ├── mysql-patterns.md        # MySQL/MariaDB (AUTO_INCREMENT, JSON, UPSERT)
│   │   └── threading-patterns.md    # Threading (TThread, TTask, Synchronize/Queue)
│   └── skills/                      # On-demand skills (SKILL.md per folder — Claude docs standard)
│       ├── clean-code/              # Clean Code and Pascal Guide
│       ├── delphi-memory-exceptions/# Memory management and try..finally
│       ├── delphi-patterns/         # Repository, Service, Factory
│       ├── design-patterns/         # Design Patterns GoF (23 patterns)
│       ├── refactoring/             # Refactoring (10 techniques, before/after)
│       ├── tdd-dunitx/              # TDD with DUnitX
│       ├── horse-framework/         # Horse REST API
│       ├── dmvc-framework/          # DelphiMVC Framework
│       ├── dext-framework/          # Dext Framework
│       ├── acbr-components/         # ACBr components
│       ├── intraweb-framework/      # Intraweb WebApps
│       ├── devexpress-components/   # DevExpress UI
│       ├── dunitx-testing/          # Unit testing
│       ├── firebird-database/       # Firebird Database (connection, PSQL, generators)
│       ├── postgresql-database/     # PostgreSQL Database (UPSERT, JSONB, FTS, PL/pgSQL)
│       ├── mysql-database/          # MySQL/MariaDB (AUTO_INCREMENT, JSON, FULLTEXT)
│       ├── threading/               # Threading (TThread, TTask, PPL, thread-safety)
│       └── code-review/             # Code review
│
├── .github/
│   └── copilot-instructions.md      # 🤖 Pre-prompt for GitHub Copilot
│
├── .cursor/
│   └── rules/                       # Same rule files as .claude/rules/ (Cursor format)
│
├── .gemini/
│   └── skills/                      # Same skill folders as .claude/skills/ (Gemini format)
│
├── .kiro/
│   └── steering/
│       ├── product.md               # Product vision
│       ├── tech.md                  # Technology stack
│       ├── structure.md             # Layer architecture
│       └── frameworks.md            # Framework guides
│
├── .specify/                        # AI-assisted spec templates
│   ├── constitution.md              # Project constitution and constraints
│   ├── plan-template.md             # Implementation plan template
│   ├── spec-template.md             # Feature specification template
│   └── tasks-template.md            # Task breakdown template
│
├── tools/                           # Utility scripts
│   ├── neural_translate_en.py       # Neural translation helper
│   ├── translate_comment_markers_en.py # Comment marker translation
│   └── translate_to_en_us.ps1       # PowerShell translation script
│
└── examples/
    ├── clean-unit-example.pas        # Well-organized unit (Golden Path)
    ├── memory-exception-example.pas  # Correct memory and exception patterns
    ├── repository-pattern.pas        # Complete Repository Pattern
    ├── service-pattern.pas           # Complete Service Pattern
    ├── design-patterns-example.pas   # Design Patterns GoF in practice
    ├── refactoring-example.pas       # Refactoring before/after (6 techniques)
    ├── tdd-dunitx-example.pas        # TDD and DUnitX in practice
    ├── horse-api-example.pas         # REST API with Horse
    ├── dmvc-controller-example.pas   # DMVC Controller with Attributes
    ├── dext-api-example.pas          # Minimal API with Dext
    ├── acbr-service-example.pas      # NF-e issuance with ACBr
    ├── intraweb-form-example.pas     # Intraweb Form with UserSession
    ├── firebird-repository-example.pas  # Repository with FireDAC + Firebird
    ├── postgresql-repository-example.pas # Repository with FireDAC + PostgreSQL
    ├── mysql-repository-example.pas  # Repository with FireDAC + MySQL
    ├── threading-example.pas         # Threading patterns (TTask, BackgroundWorker, Producer-Consumer)
    ├── file-copy-app/                # 📦 Complete app example: file copy with service layer
    └── i18n-app/                     # 📦 Complete app example: internationalization (i18n)

---

⚡ Quick Start

1. Clone or download the kit

git clone https://github.com/delphicleancode/delphi-spec-kit.git

2. Copy to the root of your Delphi project

YourProject/
├── MyApp.dpr
├── AGENTS.md          ← copy from the root
├── .claude/           ← copy the folder
├── .github/           ← copy the folder
├── .cursor/           ← copy the folder
├── .gemini/           ← copy the folder
├── .kiro/             ← copy the folder
└── .specify/          ← copy the folder (optional — spec templates)

3. AI automatically takes over the rules

• Claude Code — Applies .claude/CLAUDE.md and uses direct rules/skills in the terminal
• Cursor — Reads .cursor/rules/*.md automatically by context
• GitHub Copilot — Reads .github/copilot-instructions.md in workspace
• Antigravity / Gemini — Skills in .gemini/skills/ are activated on demand
• Kiro — Reads .kiro/steering/*.md as fixed product context

No additional configuration required. Open the project, use your preferred AI and notice the difference.

---

💡 Examples of Good Practices

Layer Architecture

src/
├── Domain/         ← Entities, Value Objects, Repository Interfaces
├── Application/    ← Services, Use Cases, DTOs
├── Infrastructure/ ← FireDAC Repositories, external APIs
└── Presentation/   ← VCL/FMX Forms, ViewModels
tests/
└── Unit/           ← DUnitX projects with isolated Fakes

Dependency rule: Presentation → Application → Domain ← Infrastructure Domain never depends on other layers.

Guard Clauses (no unnecessary nesting)

procedure ProcessOrder(AOrder: TOrder);
begin
  if not Assigned(AOrder) then
    raise EArgumentNilException.Create('AOrder cannot be nil');
  if AOrder.Items.Count = 0 then
    raise EBusinessRuleException.Create('Order must have at least one item');
  if not AOrder.IsValid then
    raise EValidationException.Create('Order validation failed');

  //real logic here, no nesting
  FRepository.Save(AOrder);
  FNotifier.Send(AOrder.Customer.Email);
end;

Test with Fake via Interface

type
  TFakeOrderRepository = class(TInterfacedObject, IOrderRepository)
  private
    FOrders: TObjectList<TOrder>;
  public
    constructor Create;
    destructor Destroy; override;
    procedure Save(AOrder: TOrder);
    function FindById(AId: Integer): TOrder;
  end;

[TestFixture]
TOrderServiceTest = class
private
  FSut: TOrderService;
  FRepo: IOrderRepository;
public
  [Setup]
  procedure SetUp;
  [Test]
  procedure PlaceOrder_ValidOrder_SavesToRepository;
  [Test]
  procedure PlaceOrder_EmptyItems_RaisesException;
end;

---

🚫 AI Ignore / Context Checklist

This project enforces a multi-layer strategy to control what AI agents index and use as context. Before submitting a PR:

• Build output folders of any new subproject are covered by .gitignore
• .cursorignore includes any new heavy or binary paths
• Essential instruction files (AGENTS.md, rules, skills, examples) are NOT excluded
• .vscode/settings.json excludes are up to date for new artifact types
• No secrets (*.key, *.pfx, .env) are committed or referenced

See docs/ai-ignore-strategy.md for the full rationale and maintenance guide.

---

🤝 Contributions

Pull Requests are welcome! If your favorite Delphi framework or library needs a guide for AI, add:

1. Claude Rule → .claude/rules/your-framework.md
2. Claude Skill → .claude/skills/your-framework/SKILL.md
3. Cursor Rule → .cursor/rules/your-framework.md
4. Gemini Skill → .gemini/skills/your-framework/SKILL.md
5. Reference → mention in AGENTS.md

How to contribute

# Fork and clone
git fork https://github.com/delphicleancode/delphi-spec-kit
git clone https://github.com/YOUR-FORK/delphi-spec-kit

# Create a descriptive branch
git checkout -b feat/add-remobjects-patterns

# Commit and Pull Request
git commit -m "feat: add RemObjects SDK patterns"
git push origin feat/add-remobjects-patterns

---

Buy the author a coffee via Pix: pix@inovefast.com.br ☕

Made with ❤️ for the Delphi community.

If this kit helped you, leave a ⭐ in the repository!