🚀 Delphi AI Spec-Kit

Sponsorship

Delphi/Lazarus components

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

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?

---

🤖 Supported AI Tools

---

🌟 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:

---

🛠️ Supported Frameworks and Libraries

---

📂 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;
  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

---