Collaborative Specification

Spec -> Code

LLM coding agents perform really well when working from a build spec, typically in the form of an markdown document.

In my experience, the more time is spent on this spec and the more useful context is included or linked into it, the better the results. This includes business vision, stage of product rollout (R&D, MVP, mature), business context around the feature, alternatives explored and rejected, reasons why, etc.

These specs are useful to keep within the code base, since they represent a condensed definition of the code functionality that the LLM can rapidly reference. They also ideally capture the business context that is not present in the code. This is extremely helpful for the LLM with things like framework decisions, testing depth, migrations, fallbacks, etc. These decisions look very different at various product maturity levels.

Code -> Spec

LLMs coding agents are great at documenting existing code. Again, markdown docs are the norm. I’ve found embedded mermaid diagrams are super helpful for rapidly understanding existing user flows or data flows.

These docs can then form rapid access memory for the LLM when building new code, instead of having to explore and reason through the code again.

What’s interesting

  1. Standard formats for a common vocabulary
    1. Define how LLMs and humans should collaborate on specs. Both are fluent in .md (markdown) and .mmd (mermaid). What are the limitations?
  2. Closing the loop (spec->code->spec)
    1. Refining the best practices around agentic product development, something like https://github.com/github/spec-kit, but persisting the assets as a living index.
    2. Specs versioned in the repo
    3. Automatic workflows to regenerate documentation and save key decisions
      1. Final state - current complete product spec
      2. Intermediate decision context - ADRs
    4. Incorporating mid-build feedback and course corrections
  3. Summarizing / Indexing
    1. How to chunk an ever growing spec library into a context window friendly structure
    2. Goal: make this much faster and more accurate at large scale when compared to agentic code exploration.
  4. Wider organizational adoption
    1. As a founder wearing all hats - business, product, design and eng - I’ve always wanted a single source of truth for all planning. Agentic tools benefit from all of this context at every point.
    2. I believe that a huge amount of inefficiencies in large organizations come from siloed mental models / context / frameworks in these domains. Decisions are much more obvious when the business needs match the data flows and the user flows.
    3. Can this spec platform become the spec backbone for a whole organization, from customer feature ideation to design systems to system architectural principles?
  5. Voice interaction
    1. At the top of the ideation funnel, voice is often the easiest way to brainstorm
    2. Voice to .md / .mmd is very fun. Talking about concepts with an LLM and having it draw the relationships in real time seems like a great product / feature of existing ideation platforms.

Most of these topics seem best explored within a company with a widely adopted agentic coding platform (CC, Cursor, Codex) to iterate with lots of developer feedback.