Requirements in git: what version control does not track
Keeping requirements in git — as files next to the code, reviewed in pull requests — gives you what version control is good at: history, diffs, review, and one place for the code and its spec. It does not give you what requirements need on top: readers who do not work in git, a version of the agreement rather than of files, and a signal when the code or a decision moves on without the file.
The repo now contains 94 spec folders, 238 markdown files, and 15,225 lines of specification. I haven’t reopened a single one since it was marked complete.
— I Wrote 238 Specs and Never Read One Again, dev.to, September 2026
Why teams put requirements in git
The case for docs as code is strong, and developers make it well:
The biggest win for me with docs-in-repo isn’t the AI angle, it’s that pull requests can’t land without updating the relevant docs.
— Hacker News, in a thread titled “It’s time to move your docs in the repo”, March 2026
In an Ask HN thread on tracking requirements: “When the PR is merged, code and requirements both get merged (no chance to forget to update e.g. a Confluence document)” (Hacker News, 2022). And in a thread on design docs at Google, someone who worked there from 2006 to 2014 noticed “that design docs maintained in Google Docs tended to be of lower quality than those maintained in the version control repository” (Hacker News).
What git gives a requirement:
- History of every line, with who changed it and when.
- Diffs: what changed between any two points.
- Review: a pull request, with comments and approvals.
- One change for code and spec, in the same commit.
- Tags and branches to mark a point and to work apart from it.
- Checks in CI on anything in the repository.
Requirements management in GitHub and GitLab
GitHub has no requirements object. Teams keep requirements as markdown files in the repository, or as issues with labels and a project board.
GitLab has one, on its Ultimate tier: “A requirement is an artifact in GitLab that describes the specific behavior of your product.” A requirement can be marked satisfied by hand or from a CI job (GitLab documentation). It lives in the GitLab project, beside the issues, not in the repository’s files.
What version control does not track
What a change means. Git versions lines in files. A diff shows the sentence that changed — not which requirement changed, what depends on it, or which tickets and tests were built on the old wording. Specs pile up the same way: “Five specs touch it. Four are superseded. None of them says which” (dev.to).
The code moving away from the spec. A commit that changes behaviour does not have to touch the spec, even in the same repository. A Kiro user, asking for each spec to record the commit it was written against:
The git history of the spec only tells you when the spec changed — not whether the source code it references has diverged since then.
— Kiro #9435, June 2026
Decisions made outside the repository. A call on a meeting or in chat changes what is true, and the files do not move:
I don’t see how CI knows that a “decision” went stale. Like if we agreed on a call to stop using approach A, nothing in the repo changes, and CI has nothing to fail on.
— r/ClaudeAI, July 2026
Readers who do not work in git. The people who have to agree with requirements are often not developers:
Non-programmers are not used to working with Git. … In practice, they (usually PMs or feature designers) need to write their documents somewhere else. … Two-way sync tends to be quite difficult, especially across different platforms.
— Hacker News, March 2026
In the same thread: “Reviewing docs in Github isn’t great - as the post mentions, Google Docs or similar is typically where review happens” (Hacker News).
A version of the agreement. A tag marks a commit of the whole repository, code and spec together — not “the requirements the client signed on 3 March”. A pull request approval records who approved a diff; it works as a sign-off only when the people who must agree have access and read diffs. See who reviews the spec.
Docs as code vs Confluence for requirements
| Aspect | Git (docs as code) | Confluence |
|---|---|---|
| History | Every line, with its author, in the same commit as the code | Each page, with its author |
| Review | Pull requests: diffs, comments, approvals | Comments; approvals on Premium and Enterprise plans |
| Who can take part | People with access who work in git | People with an account and permission |
| Tie to the code | Same repository; can be enforced in review and CI | Links to Jira |
| A version of the whole set | A tag — of everything in the repository | None built in |
| When the work moves on | The spec drifts unless a rule stops the merge | The page drifts |
Neither tracks what a change means for the rest of the requirements. More on the other column in managing requirements in Confluence.
How to keep requirements in git and make it work
- Give every requirement a stable ID — in its heading or its file name — that code, tests and tickets can refer to.
- Keep status and version in front matter, so a script can list what is agreed, changed or built.
- Make the owners review requirement changes. Put the requirements folder in a CODEOWNERS file and turn on required review from code owners for the main branch.
- Ask about behaviour in the pull request template: does this change what the system does? Which requirement? If yes and none was touched, the review stops there.
- Tag the requirements at sign-off —
requirements-v1.2— and record who signed, and when, in the tag message or a sign-off file. - Publish the folder as a readable site or PDF for people outside git. “rendering the markdown to feel like public docs is important for getting humans to review and take it seriously. Otherwise it goes stale as soon as one dev on the project doesn’t care” (Hacker News).
- Check references in CI: every requirement ID cited in a test exists, and every agreed requirement has a test.
- Write down decisions made outside the repository the day they are made, as a change to the requirement or a decision record.
- Give non-technical reviewers their own path in. One technical writing team’s: “SMEs review first draft in Google Docs, signed-off content is added to the repo, tech leads review the PR” (r/technicalwriting, August 2026). Another commenter: “dont make them learn branches, rebases, and PR etiquette unless they actually want to” (r/technicalwriting).
Even then, the spec and the code part ways whenever a change can merge without touching the spec — spec drift.
Where Specroot fits
This is the problem Specroot works on: requirements versioned as an agreement rather than as files, which people outside git can review and sign off, and which show the work built from each version. Specroot for teams using AI coding agents.
Read next
- Managing requirements in Confluence: where it breaks — How to manage requirements in Confluence and Jira, and where it breaks: versions of the whole set, sign-off from outside the team, traceability and drift.
- Requirements baseline: what it is, with an example — A requirements baseline is the agreed version of the requirements every later change is measured against. Definition, example, scope baseline, re-baselining.
- What is spec drift? — Spec drift is the gap between what a specification says and what was built, planned or agreed from it. Why it happens, how to detect it, how to stop it.