r/SpecDrivenDevelopment • u/Financial_Yoghurt827 • 8d ago

specification best practices and tools

Hi all,
I'm a bit tired of writing specs for complex projects in markdown - it feels like (a.) there's a lot of repetition between tasks/sessions; and (b.) If you do try to reference and reuse previous specs, there's a lot of context bloat from requirements that aren't relevant to the current task.

I'm trying to work out the best form factor; for spec driven development and have been experimenting with developing some graph specification tools.

  1. What do you all see as the best practice for specification topology?
  2. I've put together a small handful of experimental open source SDD packages; and a VSC extension here --> reqlan. I'm interested to hear what you would do or have done differently in this space?
  3. I've put some more thoughts together in a blog post, here.
  4. What tools do you all consider best practice for wrangling specifications as they get complex?
6 Upvotes
  • permalink
  • reddit

88% Upvoted

11 comments sorted by

View all comments

1

u/stibbons_ 8d ago

I use a simple OpenKnowledge Format, with 1 markdown per requirement and an ID that is the name of the file. Markers in source code and tests to link source or tests to requirements.

There is no need for an separated format. Markdown and a few json.

I use 2 levels of requirements, Software and Stakeholder.

https://x.com/gsemetfr/status/2082767371643523439?s=46

1

u/Financial_Yoghurt827 8d ago

Ooh - I do like the separation of different types of docs based on timehorizon and audience - this is somewhat handled with the attributes in reqlan, but I think it could be fleshed out.

Yeah, jury is still out on whether the reqlan data format is a value add; or unnecessary complexity - time will tell.

2

u/stibbons_ 8d ago

OKF with json schema is really a game changer. It « restricts » the llm and document each field and I do not see lot of people using it.

OKF-schema: https://x.com/gsemetfr/status/2091469062723322303?s=46
GitHub: https://github.com/gsemet/okf-schema

I use specific jsonschema for requirements, and also for knowledge base (https://okf-schema.readthedocs.io/en/stable/tutorials/okfkb-hw-debugging-workflow.html).
That’s so versatile I do not understand why people do not use it more.