build-the-missing-link-not-the-missing-system

# 없는 건 시스템이 아니라 링크 하나다 ## Problem - **증상**: 백로그/이슈가 부재형으로 적혀 있다 — "진행 중 가시성이 없다", "플랫폼이 자기를 모른다". - **본능**: 그 X 를 만든다. 하트비트 메커니즘, 지식 파이프라인. - **실제**: 부품은 **대부분 이미 있고** 사슬의 링크 하나가 끊겨 있다. 그런데 부재형 증상은 전체가 없는 것처럼 읽힌다. - **흔한 오해**: "코드에 그 로직이 있으니 동작한다." — **있는 것과 프로덕션 경로에서 도는 것은 다르다.** ### 실측 1 (BSVibe #752 — "진행 중 가시성이 없다") 새 하트비트를 설계하려다 사슬을 링크별로 재봤다: | 링크 | 상태 | |---|---| | 기록 로직 (루프가 툴 콜마다 활동 기록) | **있음** | | 실시간 신호 (툴 콜이 API 프로세스에서 매번 커밋, row lock 까지) | **있음** | | 저장·읽기 엔드포인트 | **있음** | | 화면 (`RunDetail` → 타임라인 렌더) | **있음** | | **executor 경로의 생산자** | **없음** ← 이거 하나 | 결정적 측정 한 줄: ```sql SELECT count(*) FILTER (WHERE activity_type='tool_call') FROM ... GROUP BY run_id; -- 최근 프로덕션 런 전부: 0 ``` **코드에 있는 기록 로직이 프로덕션에서 한 번도 실행된 적이 없었다.** 인-프로세스 루프는 기록하는데 프로덕션 실행 경로는 executor 였기 때문. 서브시스템이 아니라 **끊긴 선 하나**였고, 결과물은 배선 + 테스트뿐이었다. ### 실측 2 (BSVibe #753 — "플랫폼이 자기를 모른다") 지식 파이프라인을 고치려다 확인했더니: **무조건 붙는 시스템 프롬프트 슬롯이 이미 있었고, executor CLI 까지 `--append-system-prompt` 로 도달하고 있었다.** 내용이 한 달 낡았을 뿐. 그리고 원래 후보였던 "지식 노트를 만든다"는 **원리적으로 안 닿았다** — 지식 시드는 런의 *의도*로 검색하는데 "플랫폼이 너에게 무엇을 주는가"는 어떤 작업 주제와도 무관하다. ## Solution 1. **사슬을 적어라.** 생산자 → 전송 → 저장 → 읽기 → 표면. 추상적으로 말고 파일·함수로. 2. **링크마다 "이게 프로덕션에서 도는가"를 측정하라.** 코드 존재가 아니라 **산출물**로. - 행이 쌓이는가? `GROUP BY` 로 세라. 0 이면 그 링크가 범인이다. - 소비자가 실제로 받는가? 그 문자열/객체를 **출력해 눈으로 봐라.** 3. **끊긴 링크만 이어라.** 나머지는 이미 테스트·검증된 코드다. 4. **원리적으로 안 닿는 후보를 먼저 탈락시켜라.** #753 의 지식 노트처럼, 그럴듯한데 전달 경로가 그 종류의 정보를 나르지 못하는 경우가 있다. 5. **이은 링크가 소비자에게 도달하는지 테스트로 고정하라** — 소스에 다 적혀 있는데 아무에게도 안 닿는 형태가 바로 이 결함의 재발이다. ```sql -- 링크 프로브의 전형: "이 기능의 산출물이 프로덕션에 실재하는가" SELECT r.id, count(a.id) FILTER (WHERE a.activity_type='<the thing>') AS produced FROM runs r LEFT JOIN activities a ON a.run_id=r.id WHERE r.created_at > now() - interval '7 days' GROUP BY r.id; -- 전부 0 → 코드는 있는데 프로덕션 경로에서 안 돈다 ``` ## Key Insights - **부재형 증상은 규모를 과장한다.** "가시성이 없다"는 가시성 시스템이 없다는 뜻이 아니라 대개 **한 경로에서만 없다**는 뜻이다. - **경로가 둘이면 한쪽은 죽어 있을 수 있다.** 네이티브/원격, 동기/비동기처럼 같은 일을 하는 두 경로가 있으면, 프로덕션이 쓰는 쪽에만 구멍이 있는지 반드시 확인하라. 유닛 테스트는 대개 살아 있는 쪽만 덮는다. - **소비자가 이미 있는 경우가 흔하다.** 보통의 half-wired 는 UI 가 먼저 나가고 producer 가 빠지는 것인데, **방향이 반대인 경우**(소비자·화면·라벨러가 다 있고 생산자만 없음)도 똑같이 흔하다. - 링크를 찾으면 **작업이 한 자릿수 배로 줄어든다.** 그 절감이 이 확인의 값어치다. ## Red Flags - 백로그 문장이 "…가 없다 / 안 보인다 / 모른다"로 끝난다. - 결론이 "새 메커니즘이 필요하다"인데 **기존 사슬을 그려본 적이 없다.** - 어떤 기능이 코드에는 있는데 **그 산출물을 프로덕션에서 본 기억이 없다.** - 같은 일을 하는 경로가 둘 이상이고, 그중 하나가 프로덕션 기본값이다. - 해결책 후보가 "데이터를 더 넣는다"인데, **그 데이터를 나르는 경로가 그 종류의 정보를 선택하는 기준**(예: 주제 유사도)과 맞지 않는다. ## 관련 - `verify-handoff-claims-against-code-before-building` — 브리프가 "안 됐다"고 한 것이 이미 됐을 때 - `half-wired-subsystem-audit` — 보이는 절반만 지어지는 반대 방향 - `seam-must-assert-what-the-consumer-sees` — 이은 링크가 실제로 닿는지 단언하기