> ## Documentation Index
> Fetch the complete documentation index at: https://engineering.datarelay.run/llms.txt
> Use this file to discover all available pages before exploring further.

# 지식과 Source of Truth

> 왜 Project Charter, WBS, Roadmap만으로 부족했고 GitHub 중심 구조로 돌아왔는지 설명합니다.

# 지식과 Source of Truth

가장 큰 교훈 중 하나는 **문서가 존재한다고 해서 AI가 실제 작업에서 읽는 것은 아니라는 점**이었습니다.

초기에는 Project Charter, WBS, Roadmap 등 여러 계획 문서를 만들었습니다. 하지만 ChatGPT와 Cursor는 실제 구현 시 이 문서를 항상 읽지 않았고, 시간이 지나면서 scope와 roadmap이 실제 코드와 달라졌습니다.

## 기존 문제

* AI가 모든 계획 문서를 자동으로 읽지 않음
* 모든 문서를 읽히면 context가 지나치게 커짐
* Scope와 roadmap이 문서보다 빠르게 바뀜
* 왜 코드 구조가 바뀌었는지가 채팅에만 남음
* 나중에는 무엇은 코드에서 보여도 왜는 남지 않음

## 현재 구조

```mermaid theme={null}
flowchart TB
    G["GitHub<br/>Code · Spec · Test · ADR · CI"] --> T["Normative Engineering Truth"]
    W["AI Work Packet"] --> C["Current Coordination State"]
    A["Athena"] --> K["Derived Searchable Knowledge"]
    H["Engineering Handbook"] --> E["Human Explanation"]
    A -. canonical reference .-> G
    H -. canonical reference .-> G
    V["Conversation"] -. 확정된 지식만 승격 .-> G
```

**GitHub는 normative source**

Code, Test, Spec, ADR, release evidence와 repository engineering metadata를 둡니다.

**AI Work Packet은 current coordination state**

지금 workstream을 이어가기 위해 필요한 현재 상태만 둡니다.

**Athena는 검색 가능한 derived knowledge**

결정 이유와 cross-project history를 찾는 데 사용하지만 runtime truth를 대신하지 않습니다.

**이 홈페이지는 설명서**

사람이 시스템을 빠르게 이해하기 위한 handbook입니다.

## 정보별로 어디에 두는가

| 정보                                  | Durable Home                       |
| ----------------------------------- | ---------------------------------- |
| 현재 runtime behavior                 | Code / config / schema             |
| 의도된 제품 behavior                     | Product Master / canonical spec    |
| 되돌리기 비싼 architecture/security 결정    | ADR                                |
| 실행 가능한 behavior 증거                  | Tests / CI                         |
| 현재 active workstream 상태             | AI Work Packet                     |
| 운영 절차                               | Runbook                            |
| Incident 학습                         | RCA + regression/runbook/spec 업데이트 |
| 검색 가능한 결정 이유와 cross-project history | Athena                             |
| Engineering System 사람용 설명           | 이 Handbook                         |
| 아직 확정되지 않은 brainstorming            | 확정되기 전까지 Conversation              |

같은 규칙을 여러 문서에 복사해서 경쟁하는 source of truth를 만들지 않는 것이 핵심입니다.

## 현장 Finding을 Durable Knowledge로 바꾸기

```mermaid theme={null}
flowchart LR
    A["Manual / Production Finding"] --> B{"무엇을 배웠나?"}
    B --> C["Regression Test"]
    B --> D["Runbook / RCA"]
    B --> E["ADR"]
    B --> F["Product Spec Clarification"]
    C --> G["GitHub"]
    D --> G
    E --> G
    F --> G
    G --> H["Athena가 검색·설명"]
```

의미 있는 finding은 chat summary로 끝나지 않고 test invariant, 운영 절차, architecture decision 또는 requirement로 남아야 합니다.

## 최소 context 원칙

AI에게 모든 것을 읽히는 것이 목표가 아닙니다.

```text theme={null}
AGENTS.md
.engineering/project.yaml
+ 작업에 필요한 tests/release metadata
+ 관련 spec/ADR/runbook 하나
+ active Work Packet
```

이 정도의 high-signal context부터 읽는 것이 기본입니다.

채팅에만 남은 결정은 durable engineering knowledge가 아닙니다.