Knowledge belongs with the product

Decisions should be available where the people and tools changing the product can use them.

The problem

Product positioning is in a slide deck. Requirements live in tickets. Design decisions are buried in chat. Architecture is maintained somewhere else. The repository contains the current implementation, but not why it exists.

A human team can sometimes bridge those gaps through shared experience. Agents don’t have that accumulated institutional memory, and repeatedly reconstructing it is expensive and error-prone.

Keeping knowledge alongside the product gives each change a durable reference point.

What belongs there

The useful knowledge depends on the discipline, but commonly includes:

• Product direction: audience, job to be done, positioning and current assumptions.
• Behaviour: requirements, acceptance criteria and decisions about edge cases.
• Architecture: responsibilities, interfaces, dependency constraints and trade-offs.
• Delivery: agreed outcomes, unresolved questions and verification evidence.
• Operations: relevant deployment constraints, diagnostics and observed behaviour.

“Alongside” need not mean a specific directory structure. It means available to the development environment, connected to the correct revision and maintained with the changes it governs. In many teams the repository is a good home; other linked systems may still be needed for commercial or organisational coordination.

Why this changes the work

Knowledge becomes executable context rather than a post-project archive. An agent implementing a bounded change can read the current product intent and only the contracts relevant to its scope. A reviewer can compare the actual change with the original decision, rather than trusting a generated explanation after the event.

Versioned decisions also make it easier to remove work. If a feature no longer supports the product strategy, the reason for removal can accompany the design and code change.

Example

A team changes its early product priority from automated triage to reliable request ownership. The product hypothesis, architecture decision, delivery plan and acceptance tests change together. A later agent does not reintroduce abandoned automation merely because it appears in an old backlog.

Limits

Documentation near code can still be stale. Proximity is not truth. Make knowledge reviewable, link decisions to tests when possible, and distinguish intentions from verified current behaviour. Avoid duplicating the same rule across many files where they can quietly diverge.

See the worked example: product brief, decision record, traceability.