왜 암묵적 지식(Tribal Knowledge)이 AI 에이전트의 레포지토리를 망가뜨리는가

모든 레포지토리(repo)에는 약간의 암묵적 지식(tribal knowledge)이 존재합니다.

모두가 실행해서는 안 된다고 알고 있는 명령어.
테스트를 시작하기 전에 반드시 먼저 실행해야 하는 서비스.
.env.example에서 누락된 환경 변수.
누군가의 기억 속에만 존재하는 설정 단계.
"이 레포지토리는 원래 이렇게 작동해"라며 아무도 설명해주지 않는 CI 동작 방식.

인간 팀에게 암묵적 지식은 이미 비용이 많이 드는 요소입니다.

AI 네이티브(AI-native) 레포지토리에게는 상황이 더 심각합니다.

이는 운영 모델(operating model)과 호환되지 않습니다.

AI 네이티브 레포지토리는 단순히 누군가가 가끔 AI 코딩 도구를 사용하는 레포지토리를 의미하지 않습니다. 이는 인간, CI, 자동화, 그리고 AI 에이전트가 모두 동일한 코드베이스를 바탕으로 추론하고, 동일한 운영 진실(operating truth)로부터 유용한 조치를 취할 것으로 기대되는 레포지토리입니다.

만약 레포지토리의 실제 규칙이 레포지토리 외부에 존재한다면, 이 모델은 무너집니다.

이것이 Ota가 존재하는 가장 명확한 이유 중 하나입니다. Ota는 인간과 AI 에이전트를 위한 소프트웨어 실행 거버넌스(software execution governance)를 중심으로 구축되었습니다. 레포지토리는 실행 방식이 어떻게 작동하는지 설명하기 위해 기억, Slack 기록, 또는 유지 관리자의 직관에 의존해서는 안 됩니다. 레포지토리는 무엇이 필요한지, 무엇이 실행 가능한지, 무엇이 안전한지, 무엇이 검증되어야 하는지, 그리고 에이전트가 어디에서 멈춰야 하는지를 선언해야 합니다.

암묵적 지식은 그 반대로 행동합니다.

규칙을 숨깁니다.

암묵적 지식은 결코 무해하지 않았습니다

팀들은 종종 암묵적 지식을 정상적인 것으로 취급합니다.

누군가 레포지토리에 합류하여 다음과 같이 묻습니다:

이걸 로컬에서 어떻게 실행하나요?

유지 관리자가 대답합니다:

아, README가 오래됐네요. 이제 pnpm을 사용하세요.

또는:

마이그레이션(migration)을 먼저 실행하되, 리셋(reset) 명령어는 실행하지 마세요.

또는:

Redis가 이미 실행 중이어야 테스트가 통과됩니다.

또는:

그 스크립트는 무시하세요. CI는 다르게 동작하니까요.

인간은 사회적 복구 계층(social recovery layer)을 가지고 있기 때문에 그런 종류의 레포지토리에서도 살아남을 수 있습니다. 후속 질문을 던질 수 있고, 망설임을 눈치챌 수 있으며, 무언가가 안전한지 물어볼 수 있습니다.

AI 에이전트에게는 그런 계층이 없습니다.

에이전트는 파일을 검사하고, 명령어를 선택하고, 체크를 실행하고, 코드를 수정하며, 상태를 보고합니다.

만약 실제 규칙이 선언되어 있지 않다면, 에이전트는 그것을 추론(inference)해야 합니다.

그리고 추론은 거버넌스(governance)가 아닙니다.

AI-Native 레포지토리에는 선언된 운영 진실(Operating Truth)이 필요합니다

에이전트가 레포지토리 내부에서 실제 작업을 수행할 것으로 기대될 때, 그 레포지토리는 AI-Native가 됩니다.

이것이 에이전트가 레포지토리를 소유한다는 뜻은 아닙니다. 이는 레포지토리가 인간이 아닌 운영자(non-human operators)에게도 판독 가능(legible)해야 함을 의미합니다.

제대로 된 레포지토리라면 다음과 같은 질문에 답할 수 있어야 합니다:

어떤 런타임(runtime)과 도구(tools)가 필요한가
어떤 설정 경로(setup path)를 먼저 실행해야 하는가
어떤 워크플로우(workflows)가 표준(canonical)인가
어떤 작업(tasks)이 선언되어 있는가
어떤 작업이 에이전트에게 안전한가
어떤 경로가 쓰기 가능한가(writable)
어떤 경로가 보호되어 있는가(protected)
무엇을 검증(verification)으로 간주하는가
어떤 차단 요소(blockers)가 승인을 필요로 하는가
어떤 상태 자동화(status automation)를 소비해야 하는가

이러한 답변들이 누군가의 머릿속에만 존재해서는 안 됩니다.

또한 README의 산문, 패키지 스크립트, CI 파일, 셸 히스토리(shell history), 오래된 이슈 댓글 등에 흩어져 있어서도 안 됩니다.

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

Ota는 레포지토리에 해당 운영 진실(operating truth)에 대한 하나의 선언된 계약(contract)을 제공합니다.

인간과 에이전트에게 매번 규칙을 재발견하도록 요청하는 대신, 레포지토리는 ota.yaml에 규칙을 선언하고 안정적인 명령 인터페이스(command surface)를 통해 이를 노출할 수 있습니다.

숨겨진 설정은 준비 상태 문제를 디버깅 문제로 변질시킵니다

AI 지원 개발에서 가장 흔한 실패 중 하나는 나쁜 코드가 아닙니다.

바로 숨겨진 설정(hidden setup)입니다.

에이전트가 테스트를 실행하고 실패를 확인한 뒤 애플리케이션을 수정하려고 시도합니다. 하지만 실제 문제는 Postgres가 실행 중이지 않았거나, 잘못된 Python 버전이 활성화되어 있었거나, 필요한 CLI가 누락되었거나, 혹은 아무도 명확하게 선언하지 않은 부트스트랩(bootstrap) 단계가 필요했을 수도 있다는 점입니다.

에이전트의 관점에서 실패는 실제 상황입니다.

레포지토리의 관점에서 실패는 오해의 소지가 있습니다.

레포지토리가 해당 작업을 수행할 준비가 되어 있지 않았던 것입니다.

이것이 숨겨진 설정 지식이 위험한 이유입니다. 이는 준비 상태의 차단 요소(readiness blockers)를 디버깅 세션으로 변질시킵니다. 인간은 시간을 낭비하고, CI는 소음이 심해지며, 에이전트는 잘못된 계층(layer)을 패치하게 됩니다.

Ota의 입장은 간단합니다: 차단 요소(blocker)를 먼저 드러내십시오.

다음과 같이 하지 마십시오:

테스트를 실행하고 충돌(crash)을 해석하십시오.

대신 다음과 같이 해야 합니다:

이 작업에는 Postgres가 필요합니다.
Postgres를 사용할 수 없습니다.
여기서 중단합니다.

그것이 더 나은 운영 모델입니다.

그것이 바로 ota doctor가 존재하는 이유입니다.

단순한 실패 패턴

이러한 실패 패턴은 항상 나타납니다:

README에는 pnpm test라고 적혀 있음
실제 테스트 경로에는 Redis도 필요함
아무도 이를 명확하게 선언하지 않음
에이전트가 테스트를 실행함
테스트가 실패함
에이전트가 애플리케이션 코드를 수정하기 시작함
실제 문제는 깨진 코드가 아니라 설정 누락이었음

이것은 AI 품질의 문제가 아닙니다.

이것은 레포지토리 진실성 (repo-truth)의 문제입니다.

거버넌스가 적용된 레포지토리라면, 그 순서는 다음과 같이 달라져야 합니다:

ota validate
ota doctor
test에 Redis가 필요함을 확인
차단 요소(blocker)에서 중단
레포지토리를 올바르게 준비
그 후에야 선언된 작업을 실행

이것이 바로 암묵적 지식 (tribal knowledge)을 계약 기반의 진실 (contract truth)로 대체했을 때 얻는 실질적인 가치입니다.

숨겨진 안전 규칙은 위험한 실행을 초래한다

암묵적 지식은 설정에 관한 것만이 아닙니다.

그것은 안전에 관한 것이기도 합니다.

모든 성숙한 레포지토리에는 무심코 실행해서는 안 되는 명령어들이 있습니다:

deploy
publish
db:reset
...

또한 검토 없이 수정해서는 안 되는 파일들도 있을 수 있습니다:

.env
lockfiles
migrations
...

인간 유지보수자는 이러한 경계를 본능적으로 알 수도 있습니다.

하지만 AI 에이전트에게는 이를 선언해 주어야 합니다.

에이전트에게 "조심해"라고 말하는 것만으로는 충분하지 않습니다. 레포지토리가 '조심한다'는 것이 무엇을 의미하는지 말해줘야 합니다.

안전한 작업은 명시적이어야 합니다.
쓰기 가능한 경로(Writable paths)는 명시적이어야 합니다.
보호된 경로(Protected paths)는 명시적이어야 합니다.
외부 상태 변이 (External-state mutation)는 승인을 필요로 해야 합니다.

이것이 Ota가 에이전트의 안전을 단순한 조언에서 실행 거버넌스 (execution governance)로 이동시키는 방식입니다.

숨겨진 검증은 잘못된 확신을 만든다

레포지토리는 또한 "완료"가 무엇을 의미하는지를 숨길 수도 있습니다.

README에는 다음과 같이 적혀 있을 수 있습니다:

PR을 열기 전에 테스트를 실행하세요.

하지만 실제 검증 경로는 다음과 같을 수 있습니다:

lint
typecheck
unit tests
...

만약 에이전트가 눈에 보이는 테스트 명령어만 실행한다면, CI(지속적 통합)는 여전히 실패하고 있음에도 성공했다고 보고할 수 있습니다.

인간도 이런 실수를 합니다.

더 깊은 문제는 레포지토리가 빠른 확인 (quick check)과 완전한 검증 (full verification) 사이의 차이를 선언하지 않았다는 점입니다.

AI 네이티브 레포지토리에서는 그 구분이 명시적이어야 합니다.

에이전트는 유한하고 선언된 검증 경로(declared verification paths)가 필요합니다. CI는 안정적인 신호(stable signals)가 필요합니다. 인간은 실제로 어떤 증거(evidence)가 생성되었는지 알아야 합니다.

이것이 바로 Ota가 '완료'를 해석에 맡기지 않고, 레포지토리에 선언된 작업(declared tasks), 워크플로우(workflows), 그리고 검증 표면(verification surfaces)을 제공하는 이유입니다.

Ota가 대체하는 것

Ota는 암묵적 지식(tribal knowledge)을 계약(contract)으로 대체합니다.

Ota를 기반으로 하는 레포지토리에서는 ota.yaml 파일이 다음 사항들을 레포지토리가 선언하는 장소가 됩니다:

런타임 및 도구 (runtimes and tools)
설정 요구사항 (setup requirements)
워크플로우 (workflows)
선언된 작업 (declared tasks)
안전한 작업 (safe tasks)
검증 작업 (verification tasks)
쓰기 가능한 경로 (writable paths)
보호되는 경로 (protected paths)
에이전트 진입점 (agent entrypoints)
실행 경계 (execution boundaries)

이는 질문을 다음에서 변경합니다:

이 레포지토리가 어떻게 작동하는지 누가 아는가?

로:

이 레포지토리가 어떻게 작동하는지에 대해 무엇을 선언했는가?

이것이 카테고리 변화입니다.

더 나은 온보딩 설명문(onboarding prose)이 아닙니다.

선언된 실행 진실(Declared execution truth)입니다.

README 설명문과 스크립트가 할 수 없는 것들

README 설명문과 헬퍼 스크립트는 유용합니다. 하지만 그것만으로는 충분하지 않습니다.

이들은 단계를 설명하거나 실행할 수는 있지만, 그 자체로는 레포지토리에 일급의 실행 계약(first-class execution contract)을 부여할 수 없습니다.

Ota는 암묵적 지식, 문서(docs), 스크립트가 자연적으로 제공하지 않는 것들을 추가합니다:

기계 판독 가능한 준비 상태 (machine-readable readiness)
실행 시작 전의 ota doctor 진단
ota validate 계약 검증
암시된 프런트 도어 대신 선언된 워크플로우
변형(mutation) 전의 드라이-런 및 미리보기 동작 (dry-run and preview behavior)
AI 에이전트를 위한 안전 작업 경계 (safe-task boundaries)
민감한 파일 및 디렉토리를 위한 보호 경로 경계 (protected-path boundaries)
인간, CI, 에이전트 모두를 위한 하나의 공유된 진실(one shared truth)

이것이 레포지토리 가이드와 레포지토리 거버넌스(repository governance)의 차이입니다.

실제 사례에서 이것이 어떻게 보이는가

작은 Ota 계약만으로도 놀라울 정도로 많은 암묵적 지식을 대체할 수 있습니다:

version: 1
project:
  name: app
...

이 계약은 인간과 에이전트에게 다음을 알려줍니다:

어떤 런타임 (runtime)이 중요한지
어떤 패키지 매니저 (package manager)가 중요한지
설정 (setup)이 무엇을 의미하는지
다음으로 어떤 태스크 (task)를 실행해야 하는지
무엇이 안전한지
무엇을 건드리면 안 되는지
변경 사항을 어떻게 검증하는지

이는 이미 유지보수자의 기억력과 오래된 README (README) 파일의 조합보다 훨씬 강력합니다.

그러면 레포지토리 (repo)는 실제 운영 흐름 (operating flow)을 갖게 됩니다:

ota validate
ota doctor
ota up --dry-run
...

이것이 추측과 통제된 실행 (governed execution) 사이의 실질적인 차이입니다.

레포지토리는 스스로를 설명할 수 있어야 합니다

암묵적 지식 (tribal knowledge)을 넘어선 레포지토리는 스스로를 설명할 수 있습니다.

다음과 같이 말할 수 있습니다:

이 레포지토리는 Node 22와 pnpm 10이 필요합니다.
설정 (setup)은 여기에 선언되어 있습니다.
빌드 (build)는 설정 (setup)에 의존합니다.
...

이것은 과도한 프로세스가 아닙니다.

이것은 운영의 명확성 (operational clarity)입니다.

이는 인간에게 더 빠른 경로를 제공합니다.
CI (CI)에게 더 깔끔한 계약 (contract)을 제공합니다.
에이전트 (agents)에게 경계 (boundaries)를 제공합니다.
유지보수자 (maintainers)에게 증거를 제공합니다.

무엇보다도, 규칙을 우연히 기억하고 있는 사람에게 레포지토리가 덜 의존하게 만듭니다.

숨겨진 규칙은 깨진 규칙입니다

README (README)가 설명할 수 있습니다.
AGENTS.md 파일이 안내할 수 있습니다.
CI (CI)가 강제할 수 있습니다.
유지보수자 (maintainers)가 결정할 수 있습니다.

하지만 레포지토리에는 이들 모두가 공유할 수 있는 선언된 운영 계층 (operating layer)이 여전히 필요합니다.

암묵적 지식 (tribal knowledge)은 그 계층을 제공할 수 없습니다.

그것은 검토 (reviewable)할 수 없습니다.
검증 (validated)할 수 없습니다.
기계가 읽을 수 (machine-readable) 없습니다.
자동화 (automation)를 위한 충분한 안정성을 갖추지 못했습니다.
에이전트 (agents)에게 안전한 경계 (safe boundary)를 제공하지 못합니다.

Ota는 가능합니다.

이것이 온보딩 (onboarding) 이상의 의미를 갖는 이유입니다. 이는 단순히 다음 개발자가 더 빨리 시작할 수 있도록 돕는 것에 관한 것이 아닙니다. 모든 동작을 추측 게임으로 만들지 않으면서, AI 에이전트 (AI agents)와 자동화 (automation)가 참여할 수 있을 만큼 실행 과정을 읽기 쉽게 만드는 것에 관한 것입니다.

결론

암묵적 지식 (tribal knowledge)은 AI 네이티브 (AI-native) 개발로 확장될 수 없습니다.

소규모 팀이 실시간으로 서로에게 질문할 수 있을 때는 작동할지 모릅니다. 하지만 인간, CI (CI), 자동화 (automation), 그리고 AI 에이전트 (AI agents) 모두가 동일한 레포지토리로부터 설명을 들어야 할 때는 작동하지 않습니다.

AI 네이티브 (AI-native) 레포지토리에는 지침 이상의 것이 필요합니다.

선언된 실행 거버넌스 (execution governance)가 필요합니다.

그들은 무엇이 요구되는지, 무엇이 안전한지, 무엇이 검증되었는지, 무엇이 차단되었는지, 그리고 무엇이 중단되어야 하는지를 명시해야 합니다.

그것이 바로 Ota가 만들어진 목적입니다.

단순히 레포지토리가 문서화된 것처럼 보이게 만드는 것이 아닙니다.

레포지토리의 실행(execution)을 통제 가능하게(governable) 만드는 것입니다.

왜냐하면 AI-native 레포지토리에서는, 숨겨진 규칙이 곧 깨진 규칙이기 때문입니다.

Ota 시작 가이드 (getting started guide) 살펴보기
Ota 예시 (examples) 레포지토리 확인하기

원문 게시처: ota.run