llm-wiki/raw/blog-topics/post-implementation-knowledge-capture-workflow-2026-05-28.md

---
title: blog-topic / post-implementation-knowledge-capture-workflow-2026-05-28
source_type: blog-topic
status: raw
related_branches: [feature-architecture-enforcement-rules]
related_projects: [ca-tmpl]
tags: [blog-topic, ca-tmpl, workflow, documentation, agent-workflow, llm-wiki]
created: 2026-05-28
status_label: ready-for-canonical
target_audience: backend-engineer
inspiration_url:
archive_url:
---

# blog-topic: post-implementation-knowledge-capture-workflow-2026-05-28

> Layer: `raw/blog-topics/` — 채용공고가 아닌 작업·학습·트러블슈팅에서 나온 블로그 글감 원석. canonical 정제 전 raw 후보이며, `wiki/blog/` 직접 생성 근거가 아니다.

## Parent / 부모

- [[raw/branch-notes/feature-architecture-enforcement-rules]] — ca-tmpl 작업 종료 조건에 LLM Wiki capture (branch-note + derived raw notes) 를 _명시적으로_ 추가한 결정 (`결정 사항 2026-05-28: non-trivial 구현 종료 조건에 LLM Wiki capture를 포함한다`).
- [[raw/project-notes/ca-skeleton-operational-contract]] — ca-tmpl skeleton 의 workflow 운영 계약 맥락.

## 트리거 / Trigger

- 트리거 유형: `branch-work`
- 트리거 날짜: 2026-05-28
- 트리거 연결 노트: [[raw/branch-notes/feature-architecture-enforcement-rules]] — 본 결정이 branch-note 의 `Decision (2026-05-28: 종료 조건에 LLM Wiki capture)` 한 줄에 압축됨. 같은 날 다른 모든 코드 결정 (Gradle / ArchUnit rule) 과 _대등한 격_ 으로 기록한 점이 핵심.

## 글감 / Topic seed

- 한 문장 요지: "구현 완료" 의 정의에 _지식 캡처 (branch-note + 파생 raw notes) 까지_ 포함해야 코드만 남고 의사결정 / 트러블슈팅 / 글감이 사라지는 걸 막을 수 있다.
- 떠오른 계기: ca-tmpl 작업에서 "branch 마치고 나면 다음 세션에서 이 결정의 _이유_ 와 _대안_ 을 다시 답할 수 없는" 반복 문제. 사용자가 매번 채팅으로 "branch-note 도 써줘" 를 요청하던 비용을 줄이기 위해 _agent prompt + repo-local rule_ 두 층에 capture rule 을 추가.
- 예상 제목 후보:
  - "구현 완료" 의 정의에 지식 캡처를 포함하기 — repo-local workflow 설계
  - LLM 에게 "코드 끝나면 branch-note 도 써" 라고 매번 요청하지 않으려면
  - branch-note · errors · interviews · blog-topics 의 _네 갈래_ 캡처 워크플로우

## 핵심 주장 후보 / Claim candidates

- 사실 후보:
  - ca-tmpl repo 의 종료 조건 워크플로우는 `AGENTS.md` + 루트 `CLAUDE.md` + `.agents/plugins/ca-superpowers/rules/llm-wiki-capture.md` + `.claude/skills/ca-superpowers-workflow/SKILL.md` 의 _네 곳_ 에 capture rule 이 흩어져 있고, 각 위치는 트리거가 다르다 (대화 시작, 모듈별 작업, 비-자명한 구현 종료, skill 호출) — 근거: `feature-architecture-enforcement-rules.md` §진행 중 메모 2026-05-28 "워크플로우 반영: ca-tmpl repo 내부 `AGENTS.md`, `CLAUDE.md`, `.agents/plugins/ca-superpowers/`, `.claude/`, `.codex/` 지침에 ... 캡처 규칙을 추가".
  - 캡처 단위는 4종 — `raw/branch-notes/`, `raw/errors/`, `raw/interviews/`, `raw/blog-topics/` — 그리고 _canonical_ (`wiki/...`) 은 _명시 요청 없으면 생성 금지_ — 근거: `.agents/plugins/ca-superpowers/rules/llm-wiki-capture.md` §"canonical 추출 요청이 없는 한 wiki/blog/wiki/interview/wiki/portfolio/wiki/concepts/wiki/projects를 바로 만들지 않는다".
  - 모든 derived note 는 `## Parent` 로 branch-note 에 upward link, branch-note 는 `## Cluster` 로 derived note 에 downward link — _양방향 nav_ 가 의무 — 근거: 동일 rule 4번 ("파생 문서는 `## Parent`에서 branch-note로 upward link하고, branch-note의 `## Cluster / 묶음`에는 파생 문서 wikilink를 되돌려 적는다").
  - 종료 응답에는 반드시 `Wiki capture` 라인 — 갱신된 노트 / 의도적으로 생성 안 한 derived note (없음 명시) / 차단 (BLOCKED) 중 하나를 보고 — 근거: 동일 rule §Final Response Requirement.
- 경험 후보:
  - 본 결정을 _다른 코드 결정과 대등한 격_ 으로 branch-note 의 §결정 사항 마지막 한 줄로 추가 (`2026-05-28: non-trivial 구현 종료 조건에 LLM Wiki capture를 포함한다`) — 근거: `feature-architecture-enforcement-rules.md` §결정 사항 마지막 항목.
  - 본 결정의 _대안 비교_ 까지 명시: (a) 사용자 수동 요청 (누락 위험), (b) Wiki vault 내부 규칙만 (ca-tmpl 작업자가 인식 못함), (c) ca-tmpl repo-local rule (채택) — 근거: 동일 §결정 사항 마지막 항목 `검토한 대안:`.
  - 본 글의 자매 branch (`feature-application-port-usecase-contract`) 가 _이 워크플로우를 실제로 적용한 첫 사례_ — branch-note 갱신 + 3개 derived note (error, interview, blog-topic) 생성을 마지막 응답에 `Wiki capture` 로 보고 — 근거: [[raw/branch-notes/feature-application-port-usecase-contract]] §완료 후 정리 + §Cluster.
  - 워크플로우 패치 도중 도구 자동 승인 검토가 차단되어 사용자 명시 승인 후 재개한 사례 — 근거: 파생 에러 [[raw/errors/apply-patch-auto-approval-rejected-2026-05-28]].
- 의견 / 해석 후보:
  - 문서화는 _후행 작업_ 이 아니라 _완료 조건의 일부_ 가 되어야 누락이 줄어든다. 단, "기록을 강제하는 자동 장치 (CI / git hook)" 까지는 아직 가지 않았다 — 현재는 _agent workflow rule_ 수준이며 honesty 차원에서 명시 — 근거: `feature-architecture-enforcement-rules.md` 진행 중 메모 2026-05-28 "등급: `documented-only` (repo-local workflow docs; 자동 강제 장치 아님)".
  - 캡처를 _네 갈래_ (branch / error / interview / blog-topic) 로 _구조화_ 하면 코드 끝난 뒤 _즉시_ 처분 가능 — "branch-note 만 적으면 errors 가 묻히고, errors 만 적으면 interview 가 묻힘". 4갈래 분리가 _분실 방지_ 의 핵심.
  - **derived note 가 _없을 때_ "없음" 을 명시하는 것** 이 의외로 중요하다 (`Errors: 없음`, `Interview prep: 없음`). 빈 cluster section 은 "정말 없는지 검토했음" 의 증거이고, _없으면 그냥 비워두는 것_ 보다 사후 검증 가능.
  - 모든 raw note 가 _line-cited evidence_ 를 갖는 것이 (전체 글의 모든 사실 후보를 `D3` / `AT-TX-C5` 같은 ID 로 인용) **canonical wiki 로 승급할 때 _재검증 가능_** 하게 만드는 가장 큰 차이.

## Outline seed

> 각 섹션 옆에 `→ 핵심 메시지` 를 함께 명시한다.

1. 문제 — 코드는 끝났는데 _왜 이렇게 했는지_ 와 _고려한 대안_ 이 채팅 로그에만 남아 다음 세션에서 휘발 → **"기록을 매번 요청한다" 는 비용을 줄이는 게 글의 출발점.**
2. 캡처를 _완료 조건_ 으로 옮기기 — repo-local `AGENTS.md` + `CLAUDE.md` + `llm-wiki-capture.md` + skill 의 _네 위치_ → **트리거를 코드 작업 가까이에 둬야 워크플로우가 실행된다.**
3. 네 갈래 raw 구조 — branch-notes / errors / interviews / blog-topics → **분리하지 않으면 한 갈래가 다른 갈래를 묻는다.**
4. _없을 때 없음을 명시_ — empty cluster section 의 honesty → **"검토 안 함" 과 "검토 후 없음" 을 구분.**
5. 라인 인용으로 _승급 가능_ 하게 — `D3`, `AT-TX-C5` 인용 패턴 → **raw 가 canonical 로 갈 때 _재검증 가능_ 한 것은 line-cited evidence 뿐.**
6. 한계 — 자동 강제 (CI / git hook) 아님, _agent workflow rule_ 수준 → **honesty 차원에서 documented-only 등급을 글에 명시.**

## Canonical 전환 후보 / Canonical extraction candidates

- `wiki/projects/ca-skeleton/knowledge-capture-workflow.md` 후보:
  - ca-tmpl 의 실제 4 위치 capture rule (AGENTS / CLAUDE / llm-wiki-capture / skill) + 종료 응답의 `Wiki capture` 라인 형식.
  - `feature-application-port-usecase-contract` 의 적용 사례 (branch-note + 3 derived notes).
  - "양방향 nav" 강제 (`## Parent` ↔ `## Cluster`) 의 검증 방법.
- `wiki/concepts/post-implementation-knowledge-capture.md` 후보:
  - "구현 완료 조건에 지식 캡처 포함" 의 일반 원칙 (project-agnostic).
  - 캡처 단위를 4갈래 (branch / errors / interviews / blog-topics) 로 분리하는 _why_.
  - canonical 승급의 게이트 (line-cited evidence + status grading).
- 필요한 추가 검증:
  - 이후 다른 branch 작업에서 실제로 derived note 가 _자동으로_ 기록되는지 반복 관찰 (현재 1 사례 = `feature-application-port-usecase-contract`).
  - 자동 강제 장치 (git hook / CI step) 를 추가했을 때의 비용 / 효과.

## Sources / 근거 후보

- [[raw/branch-notes/feature-architecture-enforcement-rules]] — workflow rule 반영 결정 (§결정 사항 2026-05-28 마지막 항목) + §진행 중 메모 2026-05-28 워크플로우 반영 내역.
- [[raw/branch-notes/feature-application-port-usecase-contract]] — 본 워크플로우의 첫 적용 사례 (Wiki capture 결과: branch-note 갱신 + 3 derived notes).
- [[raw/errors/apply-patch-auto-approval-rejected-2026-05-28]] — workflow 문서 패치 중 도구 차단 사례.
- [[raw/interviews/post-implementation-knowledge-capture]] — 같은 작업에서 파생된 예상 면접 질문.
- repo file: `ca-tmpl/.agents/plugins/ca-superpowers/rules/llm-wiki-capture.md` — Required Capture Sequence + When No Derived Note Is Needed + Final Response Requirement (4 sections).
- repo file: `ca-tmpl/AGENTS.md` §LLM Wiki 캡처 워크플로우.
- repo file: `ca-tmpl/CLAUDE.md` §LLM Wiki capture.
- repo file: `ca-tmpl/.claude/skills/ca-superpowers-workflow/SKILL.md` §LLM Wiki Capture Before Completion.

## 미해결 / Unknown

- 아직 확인해야 할 사실: 문서 규칙 _만_ 으로 _장기적으로_ agent session 누락이 줄어드는지 (현재 1 사례 검증).
- 아직 확인해야 할 사실: 자동 강제 장치 (git hook / CI step / agent runtime check) 가 _필요한지_, 아니면 documented rule 로 충분한지.
- 과장하면 안 되는 부분: 본 워크플로우는 **`documented-only`** 다. CI / git hook 으로 자동 강제하지 않음. "자동으로 캡처된다" 같은 표현 금지.
- 과장하면 안 되는 부분: agent runtime 이 본 rule 파일들을 _실제로_ 로드하는지는 plugin/skill 구현 의존이며 ca-tmpl repo 외부 의존성 — 글에서 "어떤 runtime 에서도 동작" 같은 일반화 금지.
- 블로그로 쓰기 전에 필요한 canonical 정제: 2~3개 추가 branch 사례를 거쳐 워크플로우 안정성 확인 → `wiki/projects/ca-skeleton/knowledge-capture-workflow.md` 정제 → blog 초안.

## Decision / 처리 결정

- 액션: `promote-to-canonical`
- 이유: 신규 `wiki/projects/ca-tmpl/knowledge-capture-workflow.md` 에 post-implementation knowledge capture workflow 글감으로 반영한다.
- 다음 단계: blogify 전 자동 강제 장치가 아니라 documented workflow rule임을 유지한다.

## Related / 관련

- 관련 branch: [[raw/branch-notes/feature-architecture-enforcement-rules]] (결정), [[raw/branch-notes/feature-application-port-usecase-contract]] (첫 적용 사례).
- 관련 errors: [[raw/errors/apply-patch-auto-approval-rejected-2026-05-28]] (workflow 문서 패치 중 도구 차단).
- 관련 interview prep: [[raw/interviews/post-implementation-knowledge-capture]].
- 관련 blog topics: [[raw/blog-topics/clean-architecture-boundary-enforcement-2026-05-28]] (같은 branch 의 자매 글감), [[raw/blog-topics/transaction-port-abstraction-over-spring-transactional-2026-05-28]] (첫 적용 사례에서 나온 글감 — 본 워크플로우의 _효과 증거_).
- derived blog: 생성 전. 후보 `wiki/blog/post-implementation-knowledge-capture-workflow-YYYY-MM-DD.md`.