9.1 KiB
title, source_type, status, confidence, tags, related_projects, last_reviewed, canonical_sources, audience, target_publish, status_label
| title | source_type | status | confidence | tags | related_projects | last_reviewed | canonical_sources | audience | target_publish | status_label | ||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 구현 후 지식을 다시 Wiki로 회수하기 | blog | verified | medium |
|
|
2026-07-03 |
|
backend-engineer | ready |
구현 후 지식을 다시 Wiki로 회수하기
Parent / 부모 (필수)
- 핵심 canonical: wiki/projects/ca-tmpl/knowledge-capture-workflow
- 관련 개념 문서: wiki/concepts/clean-architecture-package-layout - ca-tmpl 문서 구조와 project/concept 분리의 배경으로만 참고한다.
타깃 독자 / Target reader
- 독자 profile: 구현 과정에서 생긴 결정을 branch note, wiki, blog로 회수하고 싶은 개발자.
- 이미 안다고 가정하는 것: branch note, project note, blog draft, wiki 문서화.
- 처음 듣는다고 가정하는 것: raw 증거, canonical 문서, derived 산출물을 분리해서 학습 루프를 만드는 방식.
도입 / Hook
구현이 끝난 뒤 가장 빨리 사라지는 것은 코드가 아닙니다. 코드는 repository에 남습니다. 사라지는 것은 “왜 이 선택을 했는가”, “어떤 대안을 버렸는가”, “어디까지 검증했고 어디부터는 추측인가” 같은 맥락입니다. 이 맥락은 채팅 로그, branch note, 테스트 실패, 작은 TODO 사이에 흩어지기 쉽습니다.
ca-tmpl의 knowledge capture workflow는 이 문제를 줄이기 위한 문서화 규칙입니다. raw 자료를 증거로 보관하고, wiki/projects와 wiki/concepts를 canonical로 정리한 뒤, blog/interview/portfolio 같은 derived 산출물을 canonical에서만 만듭니다. 이 글은 애플리케이션 기능이 아니라 작업 종료 조건으로서의 지식 회수 구조를 설명합니다.
본문 outline / Body outline
- 구현 후 사라지는 것은 코드가 아니라 결정 맥락이다.
- raw, canonical, derived를 섞지 않는다.
- branch-note와 blog-topic은 증거이고 project 문서는 설명 가능한 결정이다.
- blogify는 raw가 아니라 verified canonical에서 시작한다.
- 이 workflow는 자동화가 아니라 documentation rule이다.
본문 / Body
개발자가 나중에 다시 공부하기 어려운 이유는 “기록이 없어서”만은 아닙니다. 기록은 많습니다. branch note도 있고, daily note도 있고, 테스트 로그도 있고, raw blog-topic도 있습니다. 문제는 그 기록들이 서로 다른 신뢰도를 갖는다는 점입니다. 구현 중 적은 메모와 코드 대조를 마친 project canonical, 그리고 외부에 내보낼 블로그 초안은 같은 레이어가 아닙니다.
ca-tmpl workflow의 첫 원칙은 raw를 증거로 두는 것입니다. branch-note, daily-note, error note, blog-topic은 생각의 흔적과 구현 증거를 보관합니다. 여기에는 미확정 판단, 실패한 시도, 나중에 다듬을 글감이 들어갈 수 있습니다. raw는 귀중하지만 그대로 블로그가 되지는 않습니다.
두 번째 레이어는 canonical입니다. wiki/projects/는 내 프로젝트에서 실제로 구현됐거나 로컬 검증된 결정을 정리합니다. wiki/concepts/는 특정 프로젝트를 떠난 일반 개념과 trade-off를 정리합니다. ca-tmpl의 20개 project 문서가 중요한 이유도 여기에 있습니다. 여러 branch-note에 흩어진 결정을 주제별로 합치고, 구현 범위와 미검증 범위를 분리해서 “내가 설명할 수 있는 지식”으로 바꾸기 때문입니다.
세 번째 레이어가 derived 산출물입니다. blog, interview, portfolio는 canonical에서 파생됩니다. raw branch-note에서 바로 blog를 만들지 않는 이유는 간단합니다. raw에는 사실, 추측, 계획, 감정, 작업 중간 판단이 섞입니다. canonical을 거치면 “실제로 코드가 있는가”, “로컬에서 검증됐는가”, “prod 검증은 없는가”, “planned를 구현처럼 말하고 있지 않은가”를 먼저 정리할 수 있습니다.
이번 ca-tmpl 블로그 작업도 같은 흐름입니다. raw/blog-topics 59개는 글감 원석이었고, ingest를 통해 project canonical에 반영됐습니다. 그 뒤 blogify는 wiki/projects/ca-tmpl/*.md에서 시작했습니다. 그래서 블로그 20개는 branch-note 50여 개를 1:1로 그대로 옮긴 것이 아니라, 프로젝트 결정 주제 20개로 녹인 뒤 다시 읽을 수 있는 글로 풀어내는 구조입니다.
이 workflow의 장점은 학습 경로가 보인다는 점입니다. 어떤 글을 쓰다가 근거가 약하면 raw로 돌아가는 것이 아니라 canonical을 먼저 고칩니다. canonical이 draft라면 verified로 올릴 근거를 대조합니다. blog에 쓸 수 없는 planned 항목은 planned라고 표시합니다. 이렇게 하면 글쓰기 자체가 복습이 됩니다. 단순히 문장을 만드는 것이 아니라, 내가 어디까지 알고 어디부터 모르는지 나누는 과정이기 때문입니다.
다만 이 글은 높은 자동화를 주장하지 않습니다. canonical에 따르면 이 workflow는 runtime 기능이 아니고, git hook이나 CI로 강제되는 구조도 아닙니다. 일부 branch에서 branch-note 갱신과 derived raw note 생성이 실제로 수행됐고, raw/blog-topics 59개 ingest batch가 적용 사례로 남아 있을 뿐입니다. 따라서 confidence도 medium으로 둡니다. 문서화 규칙으로는 검증됐지만, 자동 강제 장치가 있는 것은 아닙니다.
결론적으로 knowledge capture는 ca-tmpl의 코드 기능이 아니라 학습과 설명을 위한 작업 방식입니다. 구현이 끝난 뒤 branch-note를 닫고, raw 글감을 canonical에 반영하고, verified project 문서에서 blog를 파생합니다. 이 구조를 따르면 “왜 그렇게 결정했는지”를 나중에 다시 따라갈 수 있습니다. 그게 이 블로그 묶음의 진짜 목적입니다.
코드 예제 / Code samples (있다면)
이 글은 runtime code를 설명하는 글이 아니므로 애플리케이션 코드 예제는 두지 않는다. 대신 실제 workflow는 아래 흐름으로 읽는다.
# 출처: [[wiki/projects/ca-tmpl/knowledge-capture-workflow]]
raw/branch-notes + raw/blog-topics
-> wiki/projects 또는 wiki/concepts canonical
-> wiki/blog, wiki/interview, wiki/portfolio derived output
# 출처: [[wiki/projects/ca-tmpl/knowledge-capture-workflow]]
blogify 입력으로 적합한 것:
wiki/projects/ca-tmpl/<verified-project-canonical>.md
wiki/concepts/<reviewed-or-verified-concept>.md
blogify 입력으로 피해야 하는 것:
raw/branch-notes/<branch-note>.md
raw/blog-topics/<topic-seed>.md
Sources / 근거 (canonical 인용 필수, derived layer 의무)
- wiki/projects/ca-tmpl/knowledge-capture-workflow - 이 글의 1차 canonical. runtime 구현 없음, documentation workflow, partial local 사례, 자동 강제 부재, confidence medium 경계를 따른다.
- wiki/concepts/clean-architecture-package-layout - 관련 개념 문서. ca-tmpl 문서 구조와 project/concept 분리 배경으로만 둔다.
사실 vs 의견 / Fact vs opinion 구분
- 사실: 이 문서가 다루는 것은 runtime 기능이나 애플리케이션 코드가 아니라 workflow rule과 문서화 결정이다. 근거: wiki/projects/ca-tmpl/knowledge-capture-workflow
- 사실: 일부 branch에서 branch-note 갱신과 derived raw note 생성이 수행됐고, raw/blog-topics 59개 ingest batch가 raw에서 canonical로 승격된 사례로 기록되어 있다. 근거: wiki/projects/ca-tmpl/knowledge-capture-workflow
- 사실: git hook/CI enforcement는 없고 agent workflow rule에 의존한다. 근거: wiki/projects/ca-tmpl/knowledge-capture-workflow
- 의견: 블로그 작성은 문장 생산보다 canonical을 다시 검증하는 학습 루프로 볼 때 더 효과적이다.
- 알지 못하는 것: 장기적으로 회고 품질, 면접 성과, 외부 글 반응이 얼마나 좋아지는지.
답할 수 있는 범위 / Answer boundary
- 자신 있게 답할 수 있는 후속 질문:
- 왜 raw에서 바로 blog를 만들지 않는가?
- branch-note와 project canonical의 역할은 어떻게 다른가?
- ca-tmpl 20개 project blog가 branch-note 묶음을 어떻게 학습 가능한 구조로 바꾸는가?
- 다음 글로 넘길 부분:
- git hook/CI 기반 documentation gate.
- 자동 품질 검사 확장.
- 블로그 게시 후 독자 반응이나 회고 효과 측정.
게시 체크리스트 / Publish checklist
- 모든 사실 주장에 canonical 링크 있음
- 사실 vs 의견 분리 명시됨
- 금지 마케팅 표현 없음
- 코드 예제 출처 명시
- 타깃 독자 가정과 톤 일치
/lint통과- 게시 URL 기록 (게시 후):