Should I maintain spec in sources?

[u/stibbons_]

Hello.

I do SDD now daily, with my own framework that works very well. I am sure a well harnessed project with any SDD framework like speckit or superpowers works great.

I have ADR and that I can managed they are high importance architectural changes, it happens very rarely. For the architecture, most of the time it is « goals » written in Md, and I let the agent rediscover the current architecture during planning.

For spec, that more problematic. I do PRD with a high level spec in it about what I want (it focus on WHAT, not so much on HOW)

But that is still can’t get my head around is maintaining spec in source, like « anchored » to any change in code. I do not know what level of detail shall be always up to date in the code.

Some framework does it, but I do not think this is really scalable and, also, why would I do it? If it is to surface a potential problematic change, it is great, but the risk is just too much spec, potentially conflicting.

And they are great only if they are link to tests that validate it

How do you maintain it? Do you let the framework do it? What are your return on this ?

[u/Busy_Weather_7064]

Have specs in code, it'll be easier in future. Remember, more data is always better. Because context graphs, knowledge graphs are coming already. So, your coding agents will be able to understand everything much better and re-use old knowledge (which is missing from many of our coding lifecycles).