Offer support for building an AI agent to enable Spec-Driven Development (SDD) for InterSystems IRIS applications. The spec can be created using JSON or generated using a terminal wizard.
Spec-Driven Development (SDD) is a software engineering methodology that places detailed specification documents as the central "source of truth" in the development process, as an alternative to "vibe coding" (programming based only on generic prompts).
In the age of AI agents (like Claude Code or GPT-4), SDD proposes that before generating code, developers should define explicit business rules, operational boundaries, and architectural constraints. This drastically reduces AI hallucinations and logic errors.
Key Features and Benefits of SDD with AIThe End of "Vibe Coding":
Replaces vague prompts and "command-and-pray" strategies with structured technical plans.Reduced Hallucinations: The AI follows clear guidelines, decreasing the creation of non-existent libraries or incorrect code flows.
Better Context Management: The specification acts as a continuous reference document, bypassing the "amnesia" problem of AI agents in long conversations.
"Correctness by Construction": Increases the chance of code working on the first try, reducing rework time.
Agility with Structure: Allows AI to generate code quickly, but within defined safety rails, ensuring predictability.
The SDD WorkflowDefinition (The What): The human developer creates a technical specification (usually in Markdown) with business rules, use cases, and error scenarios.
Planning (The How): The AI reads the spec and drafts a detailed technical plan for approval.
Execution (Implementation): The AI agent generates the code based on the approved plan.
Verification (Validation): The developer reviews if the output adheres to the spec and performs tests.
Sample of a spec:
{
"openapi": "3.0.0",
"info": {
"title": "Sistema de GestĂŁo de Consultas (SDD for IRIS)",
"version": "1.0.0",
"x-iris-package": "User.App.Medical",
"description": "Spec para geração automática de persistência, lógica de negócio e REST no IRIS."
},
"x-iris-settings": {
"generate-comments": true,
"error-handling": "StatusException",
"use-json-adaptor": true
},
"paths": {
"/appointment": {
"post": {
"summary": "Agenda uma nova consulta",
"operationId": "BookAppointment",
"x-iris-logic": {
"steps": [
"Validate if the doctor has availability on the provided date",
"Calculate end time (startTime + 30 minutes)",
"Save record to User.App.Medical.Appointment table",
"Return 201 with the created ID"
]
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/Appointment" }
}
}
},
"responses": {
"201": { "description": "Agendamento realizado" },
"409": { "description": "Conflito de horário" }
}
}
}
},
"components": {
"schemas": {
"Appointment": {
"type": "object",
"required": ["patientName", "doctorID", "appointmentDate"],
"x-iris-persistent": true,
"x-iris-indexes": [
{ "name": "IdxDoctorDate", "properties": "doctorID, appointmentDate", "unique": true }
],
"properties": {
"patientName": {
"type": "string",
"x-iris-type": "%String",
"x-iris-params": { "MAXLEN": 150 }
},
"doctorID": {
"type": "integer",
"x-iris-type": "%Integer"
},
"appointmentDate": {
"type": "string",
"format": "date-time",
"x-iris-type": "%TimeStamp",
"description": "Data e hora da consulta"
},
"notes": {
"type": "string",
"x-iris-type": "%String",
"x-iris-params": { "MAXLEN": 500 }
},
"status": {
"type": "string",
"default": "SCHEDULED",
"enum": ["SCHEDULED", "COMPLETED", "CANCELLED"],
"x-iris-type": "%String",
"x-iris-params": { "VALUELIST": ",SCHEDULED,COMPLETED,CANCELLED" }
}
}
}
}
}
}
