---
id: gh-keeping-one-source-of-truth
name: "keeping-one-source-of-truth"
url: https://skills.yangsir.net/skill/gh-keeping-one-source-of-truth
author: riekelt
domain: ai-software-architecture-engineering
tags: ["single-source-of-truth", "data-consistency", "software-architecture", "code-maintainability"]
install_count: 17100
rating: 4.60 (120 reviews)
github: https://github.com/riekelt/principal-engineer/tree/main/plugins/principal-engineer/skills/keeping-one-source-of-truth
---

# keeping-one-source-of-truth

> 此技能指导开发者在添加数据、配置、状态、常量或缓存时识别并维护单一事实源，通过派生而非存储、扩展所有者、吸收重复项等原则，避免多副本数据漂移导致的不一致。适用于代码库中含枚举、配置映射、默认值等可能重复的场景，能显著降低因数据不一致引发的故障排查成本，提升系统可维护性和可靠性。

**Stats**: 17,100 installs · 4.6/5 (120 reviews)

## Before / After 对比

### 定位并修复数据不一致的平均耗时

**Before**:

在没有这个技能之前，开发者常因配置、枚举或常量被复制到多处而引发数据不一致。排查时需要逐个比对副本、检查哪份已经过期，往往耗费数小时，且容易遗漏隐性依赖。

**After**:

此技能通过强制单一事实源和派生机制，从源头消除重复副本。新增数据会自动被引导到正确所有者，不一致问题大幅减少，定位修复时间从数小时压缩到半小时内，系统保持健康。

| Metric | Before | After | Change |
|---|---|---|---|
| 平均修复时间 | 240分钟 | 30分钟 | -87.5% |

## Readme

# Keeping one source of truth

**REQUIRED BACKGROUND:** the `principal-engineering` skill.

## Overview

Every fact about the system lives in exactly one place, and every other part of the system reads it from there. This outranks convenience: a second copy is a future contradiction, and the copy that drifts is always the one nobody remembers exists. When two places can hold the same truth they will eventually disagree, and the system then looks healthy while serving wrong data.

## The doctrine

1. **Before adding data, find who already owns it.** Extend that owner; do not start a rival. Finding the owner is cheaper than the incident two owners eventually cause.
2. **Derive rather than store.** If the platform or an existing source can answer it at read time, read it there; do not copy the answer into a second source where it can go stale.
3. **Absorb duplicates you find on the way.** When you touch code that hardcodes what a file already knows (or the reverse), fold the two together as part of the work instead of leaving a third variant behind.
4. **A missing entry fails loud** (see `handling-failures`): the single source is only authoritative if absence from it is an error, never a silent default.
5. **Mark generated versus hand-edited, and never edit generated output.** Every artifact states which it is; edits to derived files are lost work plus a divergence.
6. **Vocabulary is typed, not stringly.** Identifiers, kinds, states, and names that code branches on are constants, enums, sealed types, or registry entries; a free string spelled twice is two sources of truth with a typo between them.
7. **When two sources disagree, say so.** One of them is stale. Surfacing the contradiction is the first fix. The full fix determines which value is live, collapses to one source, and deletes the loser. Silently following either one launders the disagreement into whichever answer you happened to read first. On a declared critical path, a live disagreement earns a direct message to the owner, not only a tracked item; an unread ticket surfaces nothing.

## Boundaries

- Caches and read models are legitimate derived copies when their derivation is automatic and their staleness is bounded and observable. The rule bans copies a person keeps in sync by hand.
- Test fixtures may freeze a copy of reality on purpose; the word fixture is the label that says so.
- Documentation follows the same rule (an index routes, never decides); the technical-writer plugin's `technical-writing` skill carries that side where installed.

## Common mistakes

- Copying a threshold, URL, or mapping "temporarily". Temporary copies have the same lifetime as the TODO above them.
- Creating `thing-v2` beside `thing` instead of editing in place. The second file is a fork of the truth, and both will receive different fixes.
- A default value in code that shadows the config file's value. When someone changes the config and nothing happens, this is why.
- Two enums in two services spelling the same states. The day one gains a state, the boundary between them becomes a silent filter.


---
*Source: https://skills.yangsir.net/skill/gh-keeping-one-source-of-truth*
*Markdown mirror: https://skills.yangsir.net/api/skill/gh-keeping-one-source-of-truth/markdown*