donghyeon.kang/llm-wiki
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Files
4e6374141bb9cd108294f7921cd4ff390dfe94bd
llm-wiki/raw/blog-topics/post-implementation-knowledge-capture-workflow-2026-05-28.md
T

12 KiB
Raw Blame History

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

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

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

Parent / 부모

트리거 / 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 / 근거 후보

미해결 / 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 / 관련

Reference in New Issue View Git Blame Copy Permalink