In the age of agents, every vendor wants to be the system of record. The context layer. The source of truth your agents should read from.
In software delivery, the useful question is which facts each system holds, and how much we can rely on them.
Where the term comes from
System of record is a data-management term. It describes the authoritative source for a particular piece of information, such as a customer's billing address. Several systems may hold a copy. The organization agrees which one to trust when the copies disagree.
Think of the land registry. The mortgage, the insurance policy, and the mail on the doorstep all refer to a house. The registry has authority over ownership. Its authority has a scope.
In software delivery, that scope might be a work item's priority, an approved design, a code revision, or a deployment event. Naming the fact comes before naming the tool.
Geoffrey Moore's 2011 distinction between systems of record and systems of engagement is useful here. My shorthand for the distinction:
A tool people use every day is a system of engagement. A tool they open to settle an argument is a system of record.
A tool can serve both roles. A pull request is a place to discuss a change and a record of its approval. The distinction applies to the fact being recorded, not the product as a whole. Figma can hold the agreed design while GitHub holds the implementation; neither establishes what is running in production.
The records across our stack
At Bytebase, six tools hold different parts of our software delivery record.
Slack holds the conversation around the work. Threads capture context and tradeoffs, but a decision left only in a thread is fragile. Summarizing the decision and its rationale in Linear gives the work a record that survives losing the conversation.
Linear tracks the work. Each issue holds its scope, priority, owner, and status. Closing it records completion in the workflow; deployment evidence establishes whether it shipped.
Google Docs holds the detailed technical design. Design documents explain the problem, approach, alternatives, and tradeoffs. A clear decision tied to a version records what was agreed.
Figma holds interface design intent. Flows and mockups describe the intended experience. The relevant design version helps explain where the shipped interface differs from what was agreed.
GitHub holds the code and its review. Commits identify source revisions; pull requests capture discussion and approvals. For Bytebase Cloud, GitHub Actions also holds the build and deployment run history. A completed workflow and a confirmed rollout are separate facts.
Terraform connects infrastructure configuration to managed resources. Configuration is reviewed in GitHub; state binds it to real resources. Checking their current condition requires reading the provider.
The life of a feature
Imagine adding audit report exports:
- Discuss in Slack. Support shares the customer request. The team chooses CSV downloads first to ship sooner, deferring scheduled emails.
- Scope in Linear. An issue names the owner and scope: CSV exports for a selected date range. It preserves the decision to defer emails and the reason, with a link to the Slack discussion.
- Design in Google Docs and Figma. The technical document specifies generation, storage, and access. Figma shows the date picker and download flow. Both link from the issue.
- Implement in GitHub. The pull request links to the issue and reviewed design versions. The diff records what changed; the review records who approved it.
- Provision with Terraform. Configuration defines the report storage bucket; state binds it to the provisioned resource. The configuration change is reviewed in GitHub.
- Deploy through GitHub Actions. The run records the source commit, build, and deployment steps. Confirmation from the target environment establishes that the new version is running.
Months later, someone reports missing scheduled emails as a bug. Linear preserves both the decision and its rationale. GitHub shows whether the implementation matched that scope.
That answer depends on records the walkthrough deliberately preserved. Leave the rationale only in Slack, link to a design without identifying the reviewed version, or let the deployment logs expire, and part of the history is lost.
An agent reading the latest design could mistake a later revision for the one that shipped. Giving it access to every tool does not resolve which record answers the question.
Where the database sits
The audit export feature also needs a table to track report jobs, status, and output file locations. GitHub records the migration that creates it and who approved the code. That record stops at the script: it does not establish that the migration ran against a particular database. Execution needs its own evidence—the target database, who ran it, when, and the result—linked back to the reviewed migration.
The same need extends beyond schema changes. Data corrections, queries, and access changes each leave a different record:
| Operation | What the record should establish |
|---|---|
| Run a schema migration | The target database, schema change, approval, executor, time, and result |
| Correct data in production | The statement, the rows it touched, who approved |
| Query data ad hoc | Who read which table, when, and whether it held sensitive data |
| Grant access | Who may touch what, granted by whom, until when |
| Hand out a credential | Who held it and when it was used |
Migration history, database audit logs, access records, and approval tickets may already hold these facts. For the audit export feature, linking the migration's execution back to its pull request would complete that part of the story. An emergency fix made directly in the database needs its own record and a link back to the work that prompted it.
Without those links, settling an argument still means piecing together scripts, tickets, Slack messages, and the DBA's memory.
Can we do better? That is the next post.
References
- System of record, Wikipedia
- Systems of Engagement and the Future of Enterprise IT, Geoffrey Moore, AIIM, 2011
- Purpose of Terraform State, HashiCorp
Ask ChatGPT