Loop Engineering 개선을 위한 Truthmark 활용: AI 코딩 에이전트를 위한 사실 계층 (Fact Layer)

AI 코딩 에이전트 (AI coding agents)는 코드를 변경하는 데 매우 능숙합니다. 그것이 바로 문제입니다.

현대적인 AI 개발 루프 (AI development loop)는 종종 다음과 같은 모습을 띱니다:

프롬프트 (prompt) → 코드 변경 (code change) → 테스트 (test) → 수정 (fix) → 리팩터링 (refactor) → 테스트 (test) → 기능 추가 (add feature) → 다시 수정 (fix again) → 핸드오프 (handoff)

이 루프는 빠르게 움직일 수 있습니다. 또한 제품을 조용히 변화시킬 수도 있습니다.

루프 엔진 (loop engine)은 지속적으로 코드를 수정하고 추가할 수 있습니다. 개별적인 각 변경 사항은 합리적으로 보일 수 있습니다. 테스트는 여전히 통과할 수도 있습니다. 디프 (diff)가 위험해 보이지 않을 수도 있습니다. 하지만 많은 반복을 거치면서 프로젝트의 실제 동작은 미묘한 방식으로 변할 수 있습니다: 타임아웃 (timeout)이 변경되거나, 엣지 케이스 (edge case)가 사라지거나, 제품 제약 조건 (product constraint)이 완화되거나, API가 거부해야 할 무언가를 수락하기 시작하거나, 아키텍처 경계 (architectural boundary)가 불분명해질 수 있습니다.

이 지점에서 Truthmark가 유용합니다.

Truthmark는 AI 지원 개발을 위해 저장소 수준의 "사실 계층 (fact layer)"을 추가합니다. 채팅 기록 (chat history), 숨겨진 메모리 (hidden memory), 또는 원시 코드 (raw code)로부터 의도를 재구성하는 리뷰어의 능력에 의존하는 대신, Truthmark는 사람이 확인 가능하고 Git 리뷰가 가능한 진실 문서 (truth documents)를 저장소에 유지합니다. 명시된 목표는 간단합니다: 에이전트 (agents)는 코드를 작성하고, Truthmark는 사람이 Git에서 검토할 수 있는 문서를 유지하는 것입니다. (github.com)

루프 엔지니어링 (loop engineering)의 문제점

루프 엔지니어링은 단순히 "테스트가 통과할 때까지 에이전트가 코드를 작성하게 만드는 것"이 아닙니다.

실제 팀에서 좋은 루프는 세 가지를 제어해야 합니다:

1. 기능적 품질 (Functional quality): 코드가 제대로 작동하는가?
2. 제품 품질 (Product quality): 동작이 여전히 의도된 제품과 일치하는가?
3. 경험 품질 (Experience quality): 사람이 이해하고, 검토하고, 작업을 계속할 수 있는가?

대부분의 에이전트 루프 (agent loops)는 첫 번째 포인트에 크게 집중합니다. 그들은 테스트를 실행하고, 에러를 읽고, 코드를 패치하며, 이를 반복합니다. 그것은 유용하지만, 불완전합니다.

테스트가 제품의 완전한 진실(truth)을 대변하지는 않습니다. 테스트는 대개 알려진 사례들을 인코딩할 뿐, 전체적인 동작 계약(behavioral contract)을 담고 있지는 않습니다. 코드 리뷰(Code review) 또한 한계가 있으며, 특히 리뷰어가 여러 번의 AI 반복(iteration)을 통해 생성된 방대한 diff를 전달받을 때 더욱 그러합니다. 리뷰어는 무엇이 변했는지는 볼 수 있지만, 왜 변했는지, 그 변화가 의도된 것인지, 혹은 이전의 제품 결정 사항과 충돌하는지는 항상 알 수 없습니다.

AI 채팅 기록(Chat history)도 이 문제를 해결하지 못합니다. 채팅 기록은 종종 비공개적이거나, 휘발적이며, 내용이 너무 길거나, 브랜치(branch)와 분리되어 있습니다. 미래의 에이전트 세션은 이를 볼 수 없을 수도 있고, PR을 리뷰하는 팀원은 이를 볼 수 없을 수도 있습니다. CI(지속적 통합)는 이를 진실의 원천(source of truth)으로 취급하지 않음이 분명합니다.

Truthmark은 프로젝트의 유지 관리되는 진실을 레포지토리(repo) 내부에 배치하고, 이를 코드 영역으로 라우팅하며, 일반적인 Git diff로서 리뷰할 수 있게 함으로써 이 간극을 메웁니다. 레포지토리는 Truthmark을 Git-native, 브랜치 범위(branch-scoped), 로컬 우선(local-first), 그리고 리뷰 가능한 방식으로 설명하며, 문서는 비공개 세션에 머무는 대신 브랜치를 따라 이동합니다. (github.com)

핵심 아이디어: 드리프트(drift)를 관찰 가능하게 만들기

루프 엔지니어링(loop engineering)에서 Truthmark을 지지하는 가장 강력한 논거는 "문서를 생성한다"는 것이 아닙니다.

더 강력한 논거는 다음과 같습니다:

AI 루프는 코드베이스를 끊임없이 변경합니다. Truthmark은 원치 않는 동작 드리프트(behavioral drift)를 가시화합니다.

루프 엔진은 구현 세부 사항을 여러 번 수정할 수 있습니다. 어떤 변경은 의도적입니다. 어떤 변경은 우발적입니다. 어떤 변경은 "기술적으로는 작동하지만" 제품 관점에서는 틀릴 수 있습니다.

사실 계층(fact layer)이 없다면, 루프는 새로운 상태를 테스트, 타입 체크(type checks), 린트 규칙(lint rules), 그리고 현재 프롬프트(prompt)와만 비교할 수 있습니다. Truthmark이 있다면, 루프는 새로운 상태를 유지 관리되는 레포지토리의 진실과도 비교할 수 있습니다.

그것이 루프의 본질을 바꿉니다.

다음 대신에:

테스트를 통과했는가?

루프는 다음과 같이 질문할 수 있습니다:

동작이 여전히 문서화된 제품 및 엔지니어링 진실과 일치하는가?
만약 변경되었다면, 그 변경은 의도된 것인가?
진실 문서(truth docs)를 변경해야 하는가, 아니면 코드를 수정해야 하는가?

그것은 AI 코딩을 위한 훨씬 더 나은 제어 시스템입니다.

Truthmark이 AI 코딩 루프(loop)에 통합되는 방식

Truthmark은 저장소(repo)에 워크플로 계층(workflow layer)을 설치합니다. 일반적인 변경 후 흐름은 다음과 같습니다:

에이전트(agent)가 기능 코드를 수정함
에이전트(agent)가 관련 테스트를 실행함
Truthmark이 매핑된 문서를 확인함
...

이는 Truthmark에 문서화된 종료 시점 워크플로(finish-time workflow)인 코드 작성, 테스트, 확인, 문서화, 검토(code, test, check, document, review)를 반영합니다. (github.com)

중요한 점은 Truthmark이 테스트나 코드 리뷰(code review)를 대체하기 위한 것이 아니라는 점입니다. Truthmark은 이러한 워크플로가 Git 내에 지속 가능한 정착지를 가질 수 있도록 해줍니다. 저장소 문서에는 Truthmark이 프롬프트(prompts), 메모리(memory), 사양(specs), 테스트(tests) 또는 코드 리뷰(code review)를 대체하지 않는다고 명시되어 있습니다. Truthmark의 역할은 저장소의 진실(repository truth)을 명시적으로 만들고, 이를 코드로 라우팅하며, 그 주변에 에이전트 가이드(agent guidance)를 설치하고, 그 결과를 Git에서 검토 가능하게 유지하는 것입니다. (github.com)

이러한 구분은 매우 중요합니다. Truthmark은 마법 같은 정확성 엔진(correctness engine)이 아닙니다. 이는 AI 지원 개발(AI-assisted development)을 위한 관측 가능성(observability) 및 거버넌스(governance) 계층입니다.

설정: 저장소에 Truthmark 추가하기

최소한의 설정은 다음과 같습니다:

cd /path/to/your-repo
npm install -g truthmark
truthmark config

그 다음 사용하는 AI 호스트(host)를 구성합니다:

version: 2
platforms:
  - codex
...

그 후 초기화 및 검증을 수행합니다:

truthmark init
truthmark check
git diff

Truthmark의 README는 이를 빠른 시작 경로(quick-start path)로 보여주며, 구성된 플랫폼에는 Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, Cursor가 포함될 수 있다고 명시합니다. (github.com)

초기화되면, 해당 리포지토리(repo)는 에이전트가 따라야 할 계약(contract)을 포함하게 됩니다. 여기서 중요한 점은, 에이전트가 백그라운드에서 실행되는 Truthmark 데몬(daemon)에 의존하지 않는다는 것입니다. Truthmark의 가이드에 따르면, CLI는 활성화된 Git 워크트리(worktree)를 대상으로 로컬에서 실행되는 반면, 에이전트가 실행하는 워크플로(workflow) 표면(surfaces)은 에이전트 호스트가 나중에 리포지토리 상태로부터 로드할 수 있는 커밋된 파일들입니다. (github.com)

이로 인해 워크플로는 브랜치 로컬(branch-local) 방식이 되며 검토(review)가 가능해집니다.

실질적인 루프 패턴 (Practical loop pattern)

루프 엔지니어링 (loop engineering)을 위해, Truthmark을 작업 완료 시점의 게이트(gate)이자 검토 증폭기(review amplifier)로 취급하십시오.

훌륭한 AI 루프는 다음과 같이 구성됩니다:

1. 에이전트에게 제한된 범위의 변경(bounded change)을 요청합니다.
2. 에이전트가 코드를 수정합니다.
3. 에이전트가 관련 테스트를 실행합니다.
...

Truthmark의 사용자 가이드는 다음과 같은 검토 형태를 설명합니다: 훌륭한 핸드오프(handoff)는 코드 디프(code diff), 테스트 증거(test evidence), 필요한 경우 Truth-doc 디프(truth-doc diff), 필요한 경우 라우팅 변경 사항(routing changes), 그리고 에이전트 보고서(agent report)를 보여주어야 합니다. 검토자는 어떤 Truth-doc이 해당 코드를 소유하고 있는지, 해당 문서의 업데이트가 필요했는지, 에이전트가 쓰기 경계(write boundaries) 내에 머물렀는지, 그리고 검증 증거(verification evidence)가 포함되었는지에 대해 답변할 수 있어야 합니다. (github.com)

이는 "테스트 통과, 여기 디프(diff)가 있습니다"라는 방식보다 더 높은 품질의 핸드오프입니다.

예시: 세션 타임아웃 드리프트 (session timeout drift)

당신의 제품 진실(product truth)이 다음과 같다고 가정해 봅시다:

# 세션 타임아웃 (Session Timeout)

사용자는 30분 동안 활동이 없으면 로그아웃됩니다.
...

이제 AI 루프에 "인증 미들웨어(auth middleware)를 단순화하고 불안정한(flaky) 타임아웃 테스트를 수정하라"는 요청이 내려졌습니다.

루프 도중, 에이전트는 테스트를 안정화하기 더 쉽게 만들기 위해 타임아웃을 30분에서 60분으로 변경합니다. 또한 모달(modal) 경로를 모킹(mock)하기 까다롭다는 이유로 경고 모달을 제거합니다.

테스트는 통과합니다.

Truthmark이 없다면, 검토자는 미들웨어 디프(diff)와 일부 테스트 변경 사항만을 보게 될 수 있습니다. 제품 회귀(product regression)를 놓치기 쉽습니다.

Truthmark이 있다면, 관련 코드 영역이 정전(canonical) Truth-doc으로 라우팅됩니다. 에이전트는 핸드오프 전에 코드 변경 사항을 진실 계층(truth layer)과 대조하여 조정(reconcile)해야만 합니다.

그 시점에서, 루프(loop)는 드리프트(drift)를 명시적으로 드러내야 합니다:

Truth Sync 결과:
- 코드가 세션 타임아웃을 30분에서 60분으로 변경했습니다.
- 기존 제품 진실(product truth)에 따르면 타임아웃은 30분입니다.
...

이것이 진정한 가치입니다. 단순히 문서를 위한 문서가 아니라, AI 루프가 제품을 변경했다는 것을 알려주는 빠른 신호(signal)가 되는 것입니다.

제품 품질: 결정 사항이 검토 가능해짐

제품 관리자(Product Manager)들이 이 부분에 관심을 가져야 합니다.

AI 에이전트는 구현(implementation)만 변경하는 것이 아닙니다. 코딩을 하는 동안 종종 작은 제품 결정(product decisions)을 내리기도 합니다:

• 이 필드를 선택 사항(optional)으로 만들어야 하는가?
• 이 API가 알 수 없는 값을 거부해야 하는가?
• 재시도(retries)를 조용히 처리해야 하는가?
• 비활성화된 사용자를 숨겨야 하는가, 아니면 보여줘야 하는가?
• 만료된 세션은 리다이렉트해야 하는가, 아니면 모달(modal)을 보여줘야 하는가?

사람으로만 구성된 팀에서는 이러한 결정이 주로 기획, 티켓, 설계 문서 또는 PR(Pull Request) 논의 과정에서 드러납니다. AI 보조 루프(AI-assisted loops)에서는 코드 생성 프로세스 내부에서 이러한 결정이 발생할 수 있습니다.

Truthmark은 제품 진실(product truth)과 엔지니어링 진실(engineering truth)을 분리함으로써 이를 도와줍니다. Truthmark의 구성 모델은 product/ 아래에 제품 진실을, engineering/ 아래에 엔지니어링 진실을 포함하며, 코드 표면(code surfaces)을 정전(canonical) 진실 문서에 매핑하는 라우팅을 제공합니다. (github.com)

이것이 중요한 이유는 모든 구현 변경 사항이 제품 변경 사항은 아니기 때문입니다.

캐시 리팩토링(cache refactor)은 엔지니어링 진실만 필요할 수 있습니다. 반면, 사용자에게 보이는 새로운 기능 경계(capability boundary)는 제품 진실을 업데이트해야 합니다. Truthmark의 설치된 워크플로 런타임(installed workflow runtime)에 따르면, Truth Sync는 정전 진실(canonical truth)을 쓰기 전에 제품 진실 결정을 내립니다. 즉, 사용자에게 보이는 약속(promise), 기능 경계(capability boundary), API 계약(API contract), 수락 기준(acceptance criterion), 또는 명시적인 사용자/제품 증거가 변경되었을 때 제품 진실을 업데이트하거나 라우팅해야 하며, 내부 구현 변경은 기본적으로 엔지니어링 진실로 처리됩니다. (github.com)

이는 팀에게 유용한 규칙을 제공합니다:

AI 루프(loop)가 사용자가 관찰할 수 있는 내용을 변경한다면, 제품 진실(product truth)을 고려해야 합니다.
시스템이 동작을 구현하는 방식만을 변경한다면, 엔지니어링 진실(engineering truth)만으로 충분할 수 있습니다.

엔지니어링 품질: 라우팅을 통한 추측 감소

AI 에이전트(AI agents)는 저장소(repo)가 크고 소유권이 암시적일 때 종종 어려움을 겪습니다.

에이전트는 다음과 같이 질문합니다: 진실의 원천(source of truth)은 어디인가? 어떤 문서가 중요한가? 어떤 테스트를 실행해야 하는가? 이 동작은 프론트엔드(frontend), 백엔드(backend), 결제(billing), 인증(auth), 또는 플랫폼(platform) 중 어디의 소유인가?

Truthmark의 라우팅(routing) 시스템은 에이전트에게 명시적인 소유권 경계를 제공합니다. 가이드에 따르면, 라우트(routes)는 에이전트에게 어떤 코드 표면(code surface)이 특정 영역에 속하는지, 어떤 진실 문서(truth docs)가 해당 영역을 소유하는지, 언제 진실을 업데이트해야 하는지, 그리고 어떤 종류의 진실 문서가 관여되는지를 알려줍니다. 또한 좋은 라우팅은 진실 동기화(Truth Sync)에 정확한 목적지를 제공하는 반면, 잘못된 라우팅은 에이전트가 추측하게 만든다고 경고합니다. (github.com)

이는 루프 품질(loop-quality)을 직접적으로 개선하는 요소입니다.

라우팅이 명확해지면, 에이전트는 자신의 작업 범위를 제한할 수 있습니다:

변경사항 파일:
- src/auth/session.ts
- tests/auth/session.test.ts
...

이를 통해 무작위적인 문서 편집을 줄이고, 에이전트가 잘못된 위치에 그림자 문서(shadow documentation)를 생성하는 것을 방지합니다.

경험 품질: 인간을 위한 더 나은 인수인계

많은 AI 엔지니어링 도구들이 에이전트의 자율성(autonomy)을 최적화하는 데 집중합니다. 이는 유용하지만, 팀에게는 인간의 신뢰(human confidence) 또한 필요합니다.

Truthmark는 인수인계(handoff)를 검토하기 더 쉽게 만듦으로써 개발자 경험(developer experience)을 개선합니다. 리뷰어에게 차이점(diff)으로부터 의도를 추론하도록 요청하는 대신, 병렬적인 진실 차이점(truth diff)을 제공합니다.

이제 리뷰어는 다음과 같이 질문할 수 있습니다:

코드 차이점(code diff)이 진실 차이점(truth diff)과 일치하는가?
동작이 실제로 변경되었기 때문에 에이전트가 문서를 업데이트했는가?
동작이 변경되지 않았을 때 에이전트가 문서 변경을 피했는가?
...

이는 엔지니어, 제품 관리자(product managers), 테크 리드(tech leads), 그리고 미래의 에이전트 모두에게 더 나은 리뷰 경험을 제공합니다.

또한 향후 AI 세션의 효율성을 개선합니다. 다음 에이전트는 오래된 채팅 기록으로부터 제품을 다시 파악할 필요가 없습니다. 대신 브랜치에 유지 관리되는 진실 문서 (truth docs)를 읽고, 저장소 로컬 워크플로 (repo-local workflow) 지침을 따를 수 있습니다.

Loop Engineering을 위한 유용한 명령어

가장 중요한 명령어는 다음과 같습니다:

truthmark config
truthmark init
truthmark check

더 고급 루프 (advanced loops)를 위한 명령어:

truthmark index
truthmark impact --base main
truthmark workflow status --workflow truthmark-sync --base main --json

Truthmark의 사용자 가이드에서는 truthmark check를 설정 (configuration), 권한 (authority), 라우팅 (routing), 프론트매터 (frontmatter), 링크 (links), 브랜치 범위 (branch scope), 생성된 서피스 (generated surfaces), 최신성 (freshness), 그리고 커버리지 진단 (coverage diagnostics)에 대한 검증이라고 설명합니다. 또한 truthmark impact --base <ref>는 변경된 파일을 라우팅된 진실 문서 (truth docs), 소유 라우트 (owning routes), 그리고 인접한 테스트 (nearby tests)에 매핑하는 방법으로 설명합니다. (github.com)

이러한 특성 덕분에 truthmark impact --base main은 특히 PR 루프 (PR loops)에서 매우 유용합니다. 다음과 같은 질문에 답하는 데 도움을 줄 수 있습니다:

이 브랜치에 의해 영향을 받는 진실 문서 (truth docs)는 무엇인가?
변경된 파일을 소유한 라우트 (routes)는 무엇인가?
에이전트가 고려해야 할 인접한 테스트 (nearby tests)는 무엇인가?

도입 권장 사항

저장소 전체를 문서화하는 것부터 시작하지 마세요.

루프에 민감한(loop-sensitive) 영역 하나부터 시작하세요:

• 인증 (authentication)
• 결제 (billing)
• 권한 (permissions)
• 온보딩 (onboarding)
• 공개 API 동작 (public API behavior)
• 데이터 보존 (data retention)
• 알림 규칙 (notification rules)
• 가격 책정 또는 플랜 제한 (pricing or plan limits)

그런 다음 에이전트에게 기존 동작을 문서화하도록 요청하세요: