Two kinds of comments

There are comments that describe what the code does. These are almost always redundant — the code already says what it does, and if it doesn’t, that’s a naming problem, not a comment problem.

Then there are comments that explain why the obvious approach was wrong. These are rare, and they are worth a hundred of the first kind. This validation exists because the upstream system sometimes sends null for a required field. The cache is invalidated here because the downstream service doesn’t respect ETags correctly. The timeout is set to 45 seconds because the legacy endpoint consistently takes 30–40 seconds on the first request.

Every one of those comments is a constraint that lives nowhere else in the codebase. It’s the accumulated knowledge of what the system actually does versus what it was designed to do. And it’s exactly what an AI coding assistant needs to not confidently recreate the bug you fixed six months ago.

Context decay in long-lived codebases

Every time a developer leaves a project, some context goes with them. The code stays. The tests stay. The history of why specific decisions were made — the customer conversation that explained the constraint, the incident postmortem that identified the failure mode, the week of debugging that finally isolated the root cause — that often doesn’t survive.

This has always been a problem. AI makes it more visible because an AI working from code alone will suggest the obvious solution with full confidence, not knowing that the obvious solution has a history.

The engineering practices that make codebases maintainable for humans also make them usable by AI. Good commit messages. Linked issues. Sprint retrospectives that capture what was learned. These aren’t overhead — they’re infrastructure.

What your issue tracker actually is

A GitLab or Jira instance that’s been used seriously is the development team’s external memory. Every issue is a record of a decision: what the problem was, what was considered, what was chosen and why. The teams that get the most from it — and increasingly, the most from AI tooling — treat it as a knowledge base. The issue isn’t done when the code ships. It’s done when anyone reading it six months later can understand the decision without asking the original developer.

Spec-driven development as context-first engineering

Writing the spec before the code is context-first development. The spec describes the constraint and the expected behavior. The code implements it. The test verifies it. Each layer is a different form of context, and each one is machine-readable by the AI working on the next iteration.

This is why spec-driven approaches work well in AI-assisted development: the AI has a complete context chain — what was intended, what was built, and whether it behaves correctly — rather than just the code in the middle.

The practical implication

None of this requires new tooling. Write commit messages that explain the why, not just the what. Link commits to the issues that prompted them. When you add a non-obvious constraint in code, add the sentence that explains it. Close issues with a summary of what was decided and why, not just a link to the merge request.

This is the unsexy version of AI readiness. Not a new model or a new platform — just a discipline around making the context that already exists actually accessible.