> ## 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.

# 개선 과정과 Lessons

> 실제 불편에서 출발해 현재 Engineering System으로 발전한 과정을 정리합니다.

# 개선 과정과 Lessons

이 시스템은 처음부터 큰 프로세스 framework를 설계한 것이 아니라 반복되는 불편을 하나씩 제거하면서 만들어졌습니다.

## Before → After

| 문제                           | 이전 방식                 | 현재 방식                                               |
| ---------------------------- | --------------------- | --------------------------------------------------- |
| AI가 계획 문서를 잘 안 읽음            | Charter, WBS, Roadmap | 작은 mandatory repository entrypoint                  |
| Scope / Roadmap drift        | 계획 문서 수동 유지           | Git / Spec / Test 중심                                |
| 구현 이유가 사라짐                   | Chat에만 결정이 남음         | Spec / ADR + Athena                                 |
| Cursor prompt가 너무 김          | 매번 복붙                 | GitHub AI Work Packet                               |
| ChatGPT Handoff가 너무 김        | Continuation Prompt   | 같은 Work Packet + 짧은 bootstrap                       |
| 아이디어 단계부터 coding agent 비용 증가 | 한 도구에서 전부 수행          | ChatGPT 설계 → Cursor 구현                              |
| 서버 실제 상태 확인이 어려움             | shell output 복붙       | Desktop Commander 직접 감사                             |
| 이동 중 긴 작업 유지 어려움             | terminal/device 종속    | Cursor CLI + tmux + 휴대폰 SSH                         |
| Cursor 완료 여부 반복 확인           | terminal polling      | Telegram 완료 알림                                      |
| Full Suite 과다 실행             | 변경마다 broad validation | affected-first, release boundary full qualification |
| 오래된 PASS 재사용 위험              | historical evidence   | exact-HEAD qualification                            |

## 변화 흐름

```mermaid theme={null}
flowchart LR
    A["많은 계획 문서"] --> B["GitHub Source of Truth"]
    B --> C["Athena<br/>결정·히스토리 검색"]
    C --> D["AI Work Packet<br/>세션 연속성"]
    D --> E["Cursor /resume"]
    E --> F["Desktop Commander<br/>독립 감사"]
    F --> G["tmux + Telegram<br/>모바일 운영"]
```

## 왜 GitHub 중심으로 돌아왔는가

Project Charter, WBS, Roadmap은 생각을 정리하는 데는 도움이 되었지만 실제 agent가 항상 읽지 않았습니다.

반면 GitHub는 이미 versioned source, PR, test, immutable commit, CI, Issue, release history를 가지고 있었습니다.

그래서 별도의 두 번째 source of truth를 만들기보다 GitHub를 중심에 두는 쪽으로 돌아왔습니다.

## Tela → Athena

결정 이유와 cross-project history를 검색할 knowledge layer는 여전히 필요했습니다.

Tela를 검토했지만 source 개수 제약 때문에 intended scale과 맞지 않아 Athena로 이동하는 방향을 선택했습니다.

Athena는 검색 계층이며 GitHub의 authority를 대체하지 않습니다.

## 다음 병목은 Context Transfer였다

GitHub 중심 구조가 잡힌 뒤 가장 큰 반복 비용은 다음이었습니다.

```text theme={null}
ChatGPT -> Cursor Prompt
Cursor -> ChatGPT 결과
ChatGPT -> 새 ChatGPT Handoff
```

Engineering System 1.3.x에서 repository-scoped AI Work Packet과 /resume을 도입해 이 수작업을 줄였습니다.

## Full Adoption 전에도 Resume이 가능해야 했다

실제 release branch에서 중요한 edge case가 발견됐습니다. Product release workstream에는 정상적인 Work Packet이 있었지만 Engineering System adoption은 별도 PR로 분리되어 있었습니다.

이때 local `AGENTS.md`나 `.engineering/*`가 없다는 이유만으로 resume을 중단하면 release 작업과 governance adoption이 섞이게 됩니다.

그래서 resume flow는 adoption이 아직 끝나지 않은 repository를 `ENGINEERING_SYSTEM_ADOPTION=ABSENT_OR_PENDING`으로 기록하고 canonical default 아래에서 계속 진행하도록 보강했습니다. Active workstream이 명시적으로 승인하지 않는 한 adoption 파일은 건드리지 않습니다.

여기서 얻은 교훈은 단순합니다. **Continuity tooling은 자신이 동작하기 위해 product scope를 바꾸지 말고 현재 repository 상태를 관찰해야 합니다.**

## 설계 원칙

> 반복 수작업을 없애거나 correctness를 명확히 높이는 경우에만 automation을 추가합니다.

Solo developer workflow가 enterprise process처럼 비대해지는 것을 막기 위한 기준입니다.