Spec-Driven Development with Markdown for AI Workflows 

AI revolutionizes software development but loses context between chats, forgets earlier architectural decisions, and produces contradictory implementations unless you keep re-explaining the same requirements.

Spec-driven development treats Markdown specifications as your single source of truth. Rather than repeating requirements in AI conversations, you maintain a single living document that captures what your application does, how it behaves, and why.

Syncfusion^® Code Studio makes this even easier with a prompt.md files (and Custom Agents), workflow files that tell your AI assistant exactly what to do at each development stage. This enables seamless specification-to-code compilation, code reviews, testing, and deployment workflows.

This blog post will guide you through implementing a practical spec-to-code workflow using prompt.md templates while building a real-world analytics dashboard example.

Why AI-assisted development breaks down

The core problem: AI context loss

When working with traditional AI‑assisted development, the AI often generates code in isolation without retaining or referencing the broader project context.
Example:

• You ask for a feature (e.g., authentication).
• The AI generates code in isolation.
• Later, you ask for changes, and the AI forgets earlier constraints (tenancy, RBAC, security rules, naming conventions).
• You repeat requirements and still get drift.

What is spec-driven development?

Spec-driven development is a methodology where:

• The specification is the source code. Your Markdown files describe the complete application design (behavior, APIs, constraints, and acceptance criteria) in plain English mixed with structured data. AI generates implementation; Code Studio’s Custom Agents compile your specification into working code.
• Every AI task references the same spec. You reduce contradictions and rework.
• Documentation stays aligned. The spec evolves alongside the code rather than becoming stale.

Example:
User: Build me a user authentication module.
AI: Generates authentication code

Spec‐driven development ensures the AI always has access to the relevant specifications. This means the generated code is not only functional but also aligned with architectural requirements, security standards, and organizational workflows:

# User Authentication Module Specification
## Overview
Multi-tenant SaaS application requiring OAuth 2.0 with role-based access control (RBAC) 
across 10,000+ organizations.
## RBAC Structure
- Organization Admin: Full access to org settings
- Team Lead: Manage team members and reports
- Member: Read-only access to team data

This format makes requirements explicit, so code generation and reviews can consistently validate against it.

How spec-driven development with Markdown works in Code Studio

What are prompt.md files?

Prompt files are workflow specifications written in Markdown that tell Code Studio’s AI what to do at each stage of development. They are the primary tool for automating your development process.

Key features:

• Repeatable instructions: Store prompts and reusable specifications to ensure consistent execution across projects.
• Task automation: Automate critical stages such as compilation, testing, code review, and deployment for faster delivery.
• Tool access: Provide AI with direct access to file operations, terminal commands, and web search for comprehensive workflow support.
• Reusable workflows: Share and apply prompt files across teams and projects to standardize development practices.
• Version control: Manage and track prompt files in Git alongside source code for full history and collaboration.

Prompt.md file format (template)

All prompt files follow this structure:

---
name: prompt file name 
mode: agent
description: Brief description of what this prompt does
---

# Main Task Title
Step-by-step instructions for the AI.
- Use bullet points for clarity
- Include specific file paths
- Reference specifications
- Define expected outputs

This structure is simple, but it’s the key to making AI output consistent and reviewable.

Spec-driven development with Markdown: Project setup (dashboard example)

Creating a complete dashboard project with the help of prompt.md files.

Recommended project structure

analytics-dashboard/
├──. codestudio/
│ └── prompts/
│ ├── compile.prompt.md
│ ├── lint.prompt.md
│ └── test.prompt.md
├── src/
│ ├── components/
│ │ ├── Dashboard.tsx
│ │ ├── Chart.tsx
│ │ └── Widget.tsx
│ └── types/
│ └── dashboard. types.ts
├── tests/
│ ├── dashboard.test.ts
│ └── api.test.ts
├── package. json
└── tsconfig. json

Note: Keep prompts in .codestudio/prompts/ so they’re easy to find, review, and run consistently.

Create your prompt files

To create Custom Prompts in Code Studio, follow these steps:

• Open Chat Window.
• Select Prompt Files.
• Click + New Prompt File and choose the location based on your preference.
• Type prompt file name.

For more insights, see our documentation on configuring custom prompts.

Create the `.codestudio/prompts/` folder and create these files:

• compile.prompt.md : Compile spec to code.
• dashboard.prompt.md: The dashboard specification.
• review.prompt.md: Code review against spec.
• security.prompt.md: Security audit.
• test.prompt.md: Test generation.
• lint-spec.prompt.md: Spec linting.

Note: You can find all these sample prompt files in this repository.

Core prompt files for spec-driven development

Convert your Markdown specification into working code:

Create compile.prompt.md (Specification to code)

---
name: compile
mode: agent
description: Compile specification to production code
---

# Compile Dashboard Specification to Code
## Task
Convert the specification in `dashboard.main.md` to working React/TypeScript code.

## Steps
1. Read Specification
   - Open and read `dashboard.main.md` completely
   - Understand all features, APIs, and database schema
2. Generate Code
   - Create components in `src/components/`
   - Create API services in `src/api/`
   - Create types in `src/types/`
3. Implement Features
   - Metric Widget component with real-time polling
   - Custom dashboard layout with drag-and-drop
   - PDF export functionality
   - Dashboard sharing
4. Test
   - Create unit tests in `tests/`
   - Run `npm run test`
   - Ensure all tests pass
5. Build
   - Run `npm run build`
   - Check for TypeScript errors
   - Verify no console warnings

Create dashboard.prompt.md

---
name: dashboard-specification
agent: agent 
description: Complete Analytics Dashboard Specification
---

## Executive Summary
Interactive real-time dashboard for SaaS analytics. End users can create. 
custom dashboard layouts, view KPIs, analyze trends, and export data.
Supports role-based access control (Admin, Manager, Viewer).

## System Architecture
### Frontend Stack
- React eighteen with TypeScript
- Recharts for data visualization
- Tailwind CSS for styling
- React DnD for drag-and-drop

### Backend Stack
- Node.js with Express
- JWT authentication

### Infrastructure
- Docker containers
- GitHub Actions CI/CD
- AWS deployment

## Feature: Real-Time Metric Widget
### User Story
As a business user, I want to see key metrics with current values and trends, So, I can quickly assess business health.

### Acceptance Criteria
1. Widget displays metric name, current value, and unit
2. Shows % change from previous period with color indicator (green: +, red: -)
3. Updates without page refresh (polling every 5 seconds)

### Testing Requirements
// Unit Tests
- Test value formatting for different units (USD, percentage, count)
- Test trend calculation (positive/negative/zero)
- Test polling interval setup and cleanup
// Integration Tests
- Test API call on mount
- Test polling updates component
- Test drill-down navigation

Create review.prompt.md: Code quality review

Review generated code against specification and best practices:

---
name: code-review
agent: agent 
description: Review code for quality and spec compliance
---
# Code Review: Spec Compliance & Quality
## Task
Review the implementation in `src/` against `dashboard.main.md`

## Review Checklist
### Code Quality
- [] Components are reusable.
- [] Clear naming conventions?
- [] Proper error handling?

## Output Format
For each issue found:
- Type: Bug | Warning | Suggestion
- Location: File path and line number
- Description: What is the issue?
- Fix: How to fix it

Create security.prompt.md: Security audit

Analyze code and specification for security vulnerabilities:

---
name: security-audit 
agent: agent 
description: Security analysis and threat modeling
---

mode: agent
description: Security analysis and threat modeling
# Security Audit
## Task
Perform security analysis on `spec/` and `src/`

## Security Checks
### Specification Review
- [] Authentication mechanism defined.
- [] Authorization rules clear?
- [] Data protection requirements specified.

### Vulnerabilities to Check
- SQL Injection
- XSS (Cross-Site Scripting)

## Output
- Risk level: CRITICAL | HIGH | MEDIUM | LOW
- Affected component
- Vulnerability description

Create test.prompt.md: Test generation

Generate comprehensive tests from specifications:

---
name: test-workflow 
agent: agent 
description: Generate tests from the specification.
---

# Generate Tests from Specification
## Task
Create comprehensive tests matching `spec/dashboard.main.md`
## Test Structure
### Unit Tests (`tests/unit/`)
- Test individual functions and components
- Test data transformations
- Test error conditions

### Integration Tests (`tests/integration/`)
- Test API endpoints
- Test database operations
- Test component interactions

## Coverage Requirements
For each feature in spec:
1. Happy path test (valid inputs, success case)
2. Error path test (invalid inputs)
3. Edge case test (boundary conditions)
4. Performance test (meets spec latency requirements

## Success Criteria
- [] All acceptance criteria have tests
- [] Test coverage > 80%
- [] All tests pass
- [] Tests run in < 5 seconds

Create lint-spec.prompt.md: Specification quality

Ensure specifications are clear and complete:

---
name: compile 
agent: agent 
description: Lint specification for quality and completeness
---

# Lint Specification
## Task
Review `spec/dashboard.main.md` for quality issues.
### Clarity
- [] All requirements unambiguous?
- [] Technical terms defined?

### Consistency
- [] Same terms used throughout?
- [] No duplicate requirements?

### Technical Feasibility
- [] Architecture realistic?
- [] Tech stack compatible?

## Issues Found
- Type: Clarity | Completeness | Consistency | Feasibility
- Issue: Description
- Severity: CRITICAL | WARNING | INFO

Automated workflow chains

Chain multiple prompts for complete automation:

.codestudio/prompts/full-workflow.prompt.md

---
name: full-workflow 
agent: agent 
description: Complete automated development workflow
---

# Full Development Workflow
Execute complete development pipeline:

## Phase 1: Specification Quality
/lint-spec.prompt.md
Wait for completion 

## Phase 2: Code Generation
/compile.prompt.md
Wait for completion 

## Phase 3: Testing
/test.prompt.md
Waiting for completion 

## Phase 4: Code Quality Review
/review.prompt.md
Wait for completion 

## Phase 5: Security Audit
/security.prompt.md
Wait for completion 

## Output Summary
- All checks passed. → Ready to merge.
- Any failures? → Report issues with fixes

Using prompts in Code Studio

Steps to start your development with prompts created:

Method 1: Via chat

Choose /full-workflow to run the entire workflow.

Code Studio:

• Reads full-workflow.prompt.md.
• Follow all instructions.
• Compiles spec to code.
• Reports completion status.

Method 2: Via command palette

• Press Ctrl+Shift+P.
• Select Chat: Run Prompt...
• Choose prompt file from list (e.g. compile.prompt.md).

Output for dashboard created using prompt files:

Note: For larger teams wanting standardized personas, Code Studio also supports Custom Agent reusable configurations that combine multiple prompt files with predefined instructions and tool access. See the Custom Agents documentation for advanced team workflows.

Conclusion

Thank you for reading! In this blog, we’ve seen how spec-driven development can take a real-world feature, like an analytics dashboard, from design to deployment.

Spec-driven development with Syncfusion Code Studio prompt.md files:

• Eliminates AI context loss across conversations and keeps documentation coordinated with code. Provides clear requirements for AI agents.
• Automates compilation, testing, review, and deployment workflows.
• Creates repeatable, consistent development processes, enables version-controlled specifications, and team alignment.
• Transform specifications directly into working code, and integrate testing and quality review into workflows.

As human–AI collaboration becomes the norm, prompt.md‑driven workflows in Code Studio offer a reliable way to preserve intent and maintain consistency.

You can contact us through our support forum, support portal, or feedback portal for queries. We are always happy to assist you!

Related Blogs

Introducing Syncfusion Agent Skills: Component-Aware AI for Accurate, Faster Development

5 min read

Spec-Driven Development with AI Using SpecKit in Syncfusion Code Studio

19 min read

Agentic AI in Software Development: From Coding to Orchestration

10 min read

Syncfusion Code Studio 2.0: AI Agents for Faster Development

9 min read