As we build software with AI agents—through tools like Cursor, VS Code, or Antigravity—Markdown files (often called specs in software development) are rapidly becoming part of the AI infrastructure layer. They act as a communication interface between humans, teams, and AI systems.
I’ve primarily used specs for two purposes.
First, for developing new features or fixing bugs. A spec becomes a development artifact where teams discuss design, trade-offs, costs, security implications, and architecture. AI agents are particularly good at exploring these aspects in depth. The entire discussion can live in one document or multiple linked documents, and when things change, agents can update the specs.
Second, for targeted analysis extracted from codebases. Sometimes you need to generate understanding for a specific audience or tool—compliance reviews, architecture analysis, cost simulations, or risk modeling. For example, I’ve built cost-simulation tools using YAML infrastructure specs derived from the codebase. The advantage is that the target audience does not need access to the entire repository—only the relevant spec.
In essence:
Specs give AI agents the structured context they need to build correctly.
They give teams clarity into why and how something was implemented.
They can be filtered and reused as inputs to other tools and analyses.
So,
MD files grows exponentially as the possibilities grow
This is where mdspec helps.
Instead of keeping specs inside every repository, teams can upload and manage their Markdown specs in mdspec, keeping repositories clean while still making specs accessible to AI agents and teams.
Your codebase stays focused on code, while mdspec becomes the structured home for specs, analysis, and cross-team collaboration.
Show HN: Mdspec.dev – let us heavylift your cluttering md files · HackerTrans
I’ve primarily used specs for two purposes.
First, for developing new features or fixing bugs. A spec becomes a development artifact where teams discuss design, trade-offs, costs, security implications, and architecture. AI agents are particularly good at exploring these aspects in depth. The entire discussion can live in one document or multiple linked documents, and when things change, agents can update the specs.
Second, for targeted analysis extracted from codebases. Sometimes you need to generate understanding for a specific audience or tool—compliance reviews, architecture analysis, cost simulations, or risk modeling. For example, I’ve built cost-simulation tools using YAML infrastructure specs derived from the codebase. The advantage is that the target audience does not need access to the entire repository—only the relevant spec.
In essence:
Specs give AI agents the structured context they need to build correctly.
They give teams clarity into why and how something was implemented.
They can be filtered and reused as inputs to other tools and analyses.
So,
MD files grows exponentially as the possibilities grow
This is where mdspec helps.
Instead of keeping specs inside every repository, teams can upload and manage their Markdown specs in mdspec, keeping repositories clean while still making specs accessible to AI agents and teams.
Your codebase stays focused on code, while mdspec becomes the structured home for specs, analysis, and cross-team collaboration.