When working with GitHub SpecKit, does maintaining a large number of spec files negatively affect context?

[harishkrishnan24]

In a long-running project where each feature or change request generates its own spec, the repository may accumulate dozens or even hundreds of specs. At that point, how do teams ensure that developers (and AI tools) can still identify which specs are relevant and current?

If older specs describe outdated assumptions or superseded decisions, can they cause confusion or incorrect implementation when someone reads them later?

From a practical standpoint, is it recommended to:

Archive older specs?

Periodically purge obsolete specs?

Keep all specs but clearly mark them as deprecated or superseded?

Are there established best practices for organizing spec files at scale (for example, by lifecycle state, version, or feature area) so that context remains clear as the project grows?

In short, how should teams balance historical record vs. contextual clarity when the number of SpecKit specs becomes large, and what lifecycle management strategies are recommended?

[awhitford]

Instead of "Archive older specs", why not just delete them since you can always see the git history?
Why do you care to maintain obsolete, deprecated specs? Isn't that what git history is all about?

Ideally, AI could optimize specs, such as:

1. Find duplicate specs
2. Group and consolidate similar specs
3. Reword specs to be more terse or precise

[harishkrishnan24]

@awhitford Thanks for your response. Yes, you could delete it if that’s possible. My concern, though, is with long-running projects. You might build a feature, move on to other work, and then come back much later to enhance that original feature. In such cases, do we create new incremental spec files? That’s the guidance I’m looking for.

[echarrod]

It probably depends on the "level" of spec-driven approach you take. But for instance if you went fully "spec as source", then you want to keep the specs around, as then when you want to modify the behaviour, you just modify the spec, and regenerate the other artifacts from that:

(from https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html)

Additionally, I think spec-kit works by looking for the next feature number which isn't present doesn't it? Wondering if this still works if you delete one, or whether it would try to recreate the feature number where it sees a "gap".

Teams are free to modify the /specify commands to adopt a branching strategy they see fit, e.g. you could split into sub-sections by product, product category, type of feature etc. (but this has the downside of making getting updates to these files require a "merge".

I think there are some discussions around this elsewhere, will update this post if I find that

[harishkrishnan24]

@echarrod Thank you for the response. If you find it please do share.

[noobAIcoder]

I don't quite understand why you need to retain any specs at all after shipping code. AI is perfectly capable of reading code and understanding what it does.

[echarrod]

If you went with the "spec as source" approach, the spec becomes the source of truth, rather than the code:

(from https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html)

Would you really want AI to read through all your code every time? It feels inefficient, and if you have spec as source, it's just considering the code with a given spec in mind when implementing, or refining if you later change the spec file

[noobAIcoder]

However, you probably do want to create and maintain updated codebase registry: a list of all modules, their interfaces, contracts and, ideally, high level logic, so that AI could read from it instead of reading all files completely every time.