Do you keep the why from AI-assisted development?

AI agents love to write a summary at the end of every task: what they changed, which files they touched, how they implemented it. It's tempting to commit these as documentation. In practice they pile up, go stale as soon as the next change lands, and repeat what the diff already shows. Worse, the next agent session reads them as current truth.

What's worth keeping is the why: the decisions, the trade-offs, and what the Product Owner actually asked for. The code shows what was done. Only people remember why, and they forget.

Don't commit AI task summaries

❌ Figure: Bad example - Bad example - AI task summaries describe what changed, duplicate the diff, and go stale after the next PR

Tell your agent not to create them. Add a line like this to your AGENTS.md:

Don't write task summary or "changes made" files. Put the reason for a change in the PR description instead.

Keep the why where people look

• PR descriptions and commit messages - Why the change was needed and what alternatives you rejected. This is the first place a reviewer or a future developer looks
• Architectural Decision Records - For significant decisions (a new library, a pattern, a data model change), write a short ADR. An ADR records one decision and its context, so it doesn't go stale when the code moves on
• Code comments - Only for non-standard code that would mislead a reader without one

Keep your Sprint Review transcripts

The Sprint Review is where the Product Owner sees the work and explains what they actually want, often with reasons that never make it into a PBI. Record it, generate a transcript (see Do you use AI for meeting notes?), and commit it to the repo:

docs/
  adr/
    0007-use-velopack-for-updates.md
  sprint-reviews/
    2026-09-12.md
    2026-09-26.md

Review the transcript before committing it, and remove anything confidential or personal that shouldn't live in source control.

Make sure your agent has the context

Stored decisions only help if your AI agent reads them. Point to them from your AGENTS.md:

## Context
- Architectural decisions: docs/adr/ - read the relevant ADR before changing architecture
- Product Owner decisions: docs/sprint-reviews/ - check recent reviews before starting a PBI

✅ Figure: Good example - Good example - The agent starts with the why, so it doesn't repeat a decision the team already made