kb-log

kb-log — 발생 시점 기록 (원장 폴백 포함)

원칙: 기록은 마무리 때 몰아서 하지 않는다. 결정/교훈이 생긴 그 턴에 기록한다. 대화 컨텍스트는 compact로 요약되고 서브에이전트 컨텍스트는 소멸하지만, kb와 원장 파일은 남는다 — 이 둘이 1차 저장소다.

무엇을 기록하나

• 결정(decision): 아키텍처·기술 선택과 그 이유, 기각한 대안. ("Redis 대신 Postgres — 운영 부담" 수준이면 충분. 사소한 스타일 선택은 제외)
• 교훈(learning): 삽질/버그의 증상 → 원인 → 예방책. 관련 파일 경로를 반드시 code_refs에 — 나중에 그 파일이 바뀌면 자동으로 재검증 큐에 올라가는 연결고리다.

절차

1. 1차: kb MCP 직접 기록 (연결돼 있으면 항상 이 경로)
   • record_decision(title, decision, context, alternatives, ...) 또는 record_learning(title, problem, root_cause, solution, prevention, code_refs=[...])
   • 응답의 similar_existing에 유사 노트가 오면: 같은 주제의 갱신이면 같은 제목으로 재기록(upsert), 옛 결정을 뒤집는 것이면 supersedes=<옛 id>로 기록해 이력을 연결한다. 무시하고 중복 생성하지 마라.
2. 2차(폴백): 원장 append — kb MCP가 없거나 실패할 때, 그리고 서브에이전트는 항상 이 경로:

   mkdir -p .kb && cat >> .kb/ledger.jsonl <<'EOF'
   {"kind": "decision", "title": "...", "body": "결정+이유+대안", "code_refs": [], "agent": "<역할>", "ts": "<ISO8601>"}
   EOF
   

   kind: decision | learning. learning이면 body에 증상/원인/예방책을 모두 담고 code_refs를 채운다. 원장은 나중에 kb-wrap이 flush한다 (Stop 훅이 잊지 않게 막아준다).
3. 비밀값·자격증명·개인정보는 어느 경로로도 기록 금지.

서브에이전트 계약 (오케스트레이터용)

서브에이전트를 띄울 때 프롬프트에 아래 블록을 포함하라 — 서브에이전트의 결정이 보고서 요약에서 유실되는 것을 막는 장치다:

작업 중 아키텍처/기술 결정을 내리거나 버그 원인을 규명하면, 종료 전에
.kb/ledger.jsonl에 한 줄 JSON으로 append하라:
{"kind":"decision|learning","title":"...","body":"결정/원인+예방책","code_refs":["경로"],"agent":"<네 역할>","ts":"<ISO8601>"}
파일이 없으면 mkdir -p .kb 후 생성. 이건 최종 보고와 별개의 의무다.

구조화 출력(schema)을 쓰는 워크플로라면 스키마에 decisions[]/learnings[] 필드를 넣어 보고 누락을 스키마 위반으로 만들고, 오케스트레이터가 수집해 원장에 append하라.