In the age of AI-assisted development, output velocity is no longer the primary bottleneck—consistency and traceability are. As engineering teams transition from manual coding to orchestrating AI agents, the risk of architectural drift, undocumented “magic” changes, and structural hallucinations becomes the greatest threat to a codebase’s longevity.
To solve this, Montinegro Corp developed and refined Spec-Driven Development (SDD): A rigorous methodology where Markdown specifications serve as the absolute source of truth, dictating all system behavior before a single line of code is written or altered.
The Core Philosophy of SDD
Spec-Driven Development asserts a simple rule: Code is merely a volatile reflection of the specification.
If a feature needs to be added, changed, or fixed, developers (and AI agents) do not touch the source code first. Instead, they update the human-readable Markdown specification. The difference between the old spec and the new spec defines the required architectural changes.
1. The 9-Digit Identifier System
To achieve bulletproof Git tracking and prevent file-deletion ghosts, we enforce a strict alphanumeric versioning system based on the format [MMM][FFFF][VV]:
[MMM](Module): A 3-digit identifier for the core business area (e.g.,014for Payments).[FFFF](Feature): A 4-digit identifier for the specific feature branch within the module (e.g.,0142for Pix Integration).[VV](Version): A base-26 two-letter suffix tracking internal document revisions (fromaatozz).
This results in a physical file name like /docs/specs/014_pagamentos/0140142_api_asaas.md.
2. The Internal Yaml Tracker
Every specification document begins with a strict YAML frontmatter header to facilitate computational tracking:
---
DOC_ID: 0140142aa
MODULE: 014
FEATURE: 0142 (Asaas Pix Integration)
---When an AI agent modifies the specification’s business logic, it auto-increments the [VV] identifier internally. This allows CI/CD pipelines and auditing tools to parse the exact state of business rules across the entire repository over time.
3. The Root Index [000]
The identifier prefix 000 is exclusively reserved for the Master Architecture Index. This root document anchors all major/minor branches relative to the entire repository and acts as a primary mirror. The physical tracking code (e.g., DOC_ID: 0000100an) mathematically translates to the semantic version (e.g., v.01.00.14) that the end-user sees.
The Active AI Workflow (Diff Tracking)
Our AI orchestration relies completely on SDD:
- Creation: To implement a new feature, a spec is created first. It is capped at 100-400 lines to enforce Single Responsibility.
- Mutation: To modify existing logic, the origin spec is updated in human language. The AI parses the semantic diff, infers the architectural blast radius, and subsequently alters the target Python or Dart code.
- Reverse Engineering: When onboarding legacy systems, the AI is instructed to read source files and backward-fill pristine Markdown specifications containing the inferred business rules.
Architectural Enforcements
Our backend uses standard Domain-Driven Design (DDD) on a Modular Monolith architecture. By keeping each domain as an isolated Django app without overlapping dependencies, we ensure the 9-digit tracking codes perfectly map to exact directory structures in the backend.
On the frontend, built natively with Flutter, we adopt a Feature-First structure organized by Atomic Design principles (Tokens, Components, Screens). The specs easily dictate which tokens and UI components are necessary, establishing a zero-ambiguity handoff from design specification to mobile rendering.
Conclusion
By adopting Spec-Driven Development and strict traceability markers, Montinegro Corp has successfully converted plain-text Markdown into a compiled, enforced structural blueprint. This not just reduces tech debt—it transforms AI coding from a chaotic generation tool into predictable, auditable, enterprise-grade engineering.