1. 왜 변경 이력을 따로 추적하나

여러 사람이 같은 공용 물건을 조금씩 고쳐 쓴다고 하자. 누가 언제 무엇을 왜 바꿨는지 아무도 적어두지 않으면, 나중에 "이거 왜 이렇게 됐지?"를 아무도 모른다.

standarda-core 와 standarda-template 이 딱 그런 공용 물건이다 — 여러 프로젝트가 함께 쓰는 패키지다. core 에 새 버전 이름표(태그)를 하나 올리거나 template 을 한 번 고치면, 그 변경은 이후 모든 프로젝트에 영향을 준다.

그런데 변경이 각 PR(코드 합치기 요청)·각 커밋에 흩어져 있으면 두 가지가 어렵다:

• 리뷰(다시 훑어보기): "지난 2주 동안 공유 패키지에 무슨 일이 있었지?"를 한눈에 못 본다.
• 교육·전파: 우리가 얻은 교훈(왜 이렇게 고쳤나)이 PR 본문 속에 묻혀 사라진다.

그래서 변경을 시간순으로 한 곳에 모은다. 이 한 곳을 SoT(Source of Truth, 믿고 보는 단 하나의 출처)라고 부른다. 오늘 다루는 추적 시스템 자체가 standarda-template PR #34 로 만들어졌고, 지금 보는 L25·L26 강의도 바로 이 기록에서 소재를 뽑아 온 것이다.

2. SoT 의 구조 — 타임라인 + 엔트리-파일

추적 SoT 는 팀 wiki 의 development/standarda-updates/ 디렉토리다(repo 밖이라 평문으로 경로만 적는다 — 사이트 링크로 걸지 않는다).

구성은 세 가지다(여기서 엔트리는 "변경 기록 한 건"을 말한다):

INDEX.md 한 줄은 이렇게 생겼다:

| 2026-06-28 | core | v0.15.0 | get_*_llm 에 timeout/max_retries 추가 | web 경로 LLM 호출엔 워커 타임아웃보다 짧은 per-call timeout | popax prod 장애 | [...](2026-06-28-core-llm-timeout.md) |

요약만 보고 싶으면 INDEX 한 줄, 배경·근본원인까지 보고 싶으면 엔트리 파일로 들어간다.

3. 왜 "엔트리는 항상 새 파일, INDEX 는 한 줄 append" 인가

설계에서 가장 중요한 규칙은 이거다 — 엔트리는 매번 새 파일로 만들고, INDEX.md 에는 한 줄만 덧붙인다(append). 기존 줄은 고치지 않는다.

이유는 여러 작업이 동시에 부딪히지 않게 하기 위해서다. 여러 프로젝트·여러 세션이 같은 날 각자 변경을 기록할 수 있다. 모두가 하나의 변경 기록 파일(changelog)을 같이 고치면, 같은 자리를 두 사람이 바꿔 부딪힌다(머지 충돌). 엔트리를 늘 새 파일로 떼고 INDEX 에는 줄을 끝에 붙이기만 하면, 서로 다른 줄·다른 파일이라 부딪힐 일이 거의 없다.

이게 standarda-template 의 옛 CHANGELOG.md 를 버리고 이 구조로 옮긴 이유 중 하나다(그 CHANGELOG.md 는 2026-06-28 부로 더 쓰지 않고 보관만 한다 — 새 변경은 거기 적지 않는다).

4. 기록을 "살아있게" 만드는 것 — 자동화 지점

SoT 를 만드는 것보다 어려운 건 계속 채워지게 하는 일이다. 사람 기억에 맡기면 곧 비어버린다.

그래서 #34 의 핵심 교훈은 이거였다:

변경 이력 SoT 는 "기록하는 자동화 지점(절차의 한 단계)"과 함께 만들어야 살아남는다.

추적 시스템은 두 개의 고정된 절차 단계에 기록을 박아 넣었다:

template 변경 → /sync-template 스킬 7단계

공통 파일을 template master 에 merge(합치기) 한 직후, 스킬이 wiki 에 엔트리를 남기게 강제한다:

### 7. wiki 변경 이력 기록 (필수)
1. _TEMPLATE.md 양식으로 새 엔트리 파일 생성
   (package: template, version: PR #번호, 📚 교육 포인트 포함)
2. INDEX.md 타임라인 표에 한 줄 append (기존 줄 수정 금지)
3. wiki commit & push
> 이 기록은 누락 금지 — template/core 변경의 유일한 시간순 SoT 다.

(template 을 기존 프로젝트에 반영하는 /update-from-template 과는 다른 방향의 스킬이다 — 그 구분은 L07.)

core 변경 → 태그 push 절차

core 는 스킬이 아니라 글로벌 CLAUDE.md 의 standarda-core 업데이트 절차 마지막 단계가 같은 일을 강제한다 — 태그 vX.Y.Z 를 push 한 직후 엔트리 + INDEX 한 줄(package: core, version: vX.Y.Z).

즉 변경이 끝나는 바로 그 자리에 기록 단계가 붙어 있다. 기록을 "나중에 몰아서"가 아니라 절차의 일부로 만든 것 — 이게 SoT 가 비지 않는 장치다.

5. 📚 교육 포인트 칸이 따로 있는 이유

INDEX 타임라인엔 변경 요약과 별개로 📚 교육 포인트 칸이 있다. 이건 "이 변경에서 배울 일반 원칙"을 한 줄로 적는 칸이다.

• v0.12.0 → "같은 provider 라도 모델군마다 받는 파라미터가 다르다"
• v0.15.0 → "web 경로 LLM 호출엔 워커 타임아웃보다 짧은 per-call timeout"

• 21 → "환경 의존 값은 standarda-template 에 박지 말고 서버 로컬 conf 를 SoT 로"

이 칸이 있어서 변경 이력이 리뷰용을 넘어 교육자료의 진입점이 된다. 실제로 L25(=#21·#28)와 L26(=v0.12.0·v0.15.0)은 이 교육 포인트 칸을 훑어 "강의로 만들 가치가 있는 것"을 고른 결과다. 이 추적 시스템은 L09 의 wiki 거버넌스, 그리고 M5 의 "교훈 전파 시스템(4층 모델)"과 같은 줄기 — 조직이 배운 것을 잃지 않게 하는 장치다.

6. 한 바퀴 — 내 변경을 한 줄 남기기

실제로 core/template 에 변경을 하나 했다고 치고 흐름을 따라가 보자(끝 실습으로 진행했으면 이 절을 남긴다):

1. 변경을 머지(template) 또는 태그 push(core) 한다.
2. _TEMPLATE.md 를 복사해 YYYY-MM-DD-{package}-{slug}.md 엔트리를 만든다 — 무엇이/왜(배경)/영향범위/📚교육포인트/출처를 채운다. "왜"는 PR 본문에서 가져온다.
3. INDEX.md 타임라인에 한 줄 append(기존 줄은 건드리지 않는다).
4. wiki 를 commit & push 한다.

이 네 단계가 template 은 /sync-template 7단계로, core 는 CLAUDE.md 절차로 이미 박혀 있으니, 절차를 따르면 자동으로 채워진다. 잊고 빠뜨렸을 때만 손으로 나중에 채워 넣는다(이걸 백필이라 한다 — 실제로 6/15 이후 19건을 한 번 몰아서 채웠다).

오늘 정리 + 다음

• 정리: 공유 패키지(core/template)의 변경은 팀 wiki development/standarda-updates/ 에 시간순 타임라인(INDEX) + 변경 1건당 엔트리 파일로 모은다. 동시 작업이 부딪히지 않게 엔트리는 새 파일, INDEX 는 끝에 한 줄 붙이기만(append-only). 무엇보다 기록을 절차의 한 단계로 박아(template=/sync-template 7단계, core=태그 push 절차) SoT 가 비지 않게 한다. 📚 교육 포인트 칸 덕에 이 기록이 곧 교육자료의 진입점이 된다.
• 흔한 함정: 변경을 "나중에 몰아서 기록"하려다 빠뜨리는 것 — 그래서 기록을 변경이 끝나는 자리에 붙였다. 또 옛 template CHANGELOG.md 에 새 변경을 적는 것(거긴 2026-06-28 동결됨, 새 변경은 wiki SoT 로).
• 다음 시간: M5 교훈 전파 시스템(4층 모델) — 변경 이력 SoT 와 짝이 되는, 코드 레벨 교훈을 어떻게 다음 작업에 주입하나.
• 자습 권장: development/standarda-updates/INDEX.md 의 최근 5줄을 읽고, 각 줄의 📚 교육 포인트가 어느 모듈 강의로 갈 만한지 분류해 보기(예: LLM 관련 → M2, 배포 관련 → M5).