왜 Runnable Repo는 항상 신뢰할 수 있는 Repo가 아닐까
Source: Dev.to
실행 가능한 레포와 신뢰할 수 있는 레포
레포가 실행될 수 있지만 여전히 신뢰하기 어려울 수 있습니다.
처음에는 이상하게 들릴 수 있습니다. 앱이 시작하고, 빌드가 완료되며, 테스트가 통과한다면 레포가 정상적으로 동작하는 것이 맞나요?
항상 그런 것은 아닙니다.
실행 가능한 레포는 특정 조건 하에서 무언가가 실행되었음을 증명합니다. 신뢰할 수 있는 레포는 그 조건을 설명하고, 경로를 반복 가능하게 만들며, 사람, CI, 자동화, 그리고 AI 에이전트가 무슨 일이 일어났는지 이해할 충분한 증거를 제공합니다.
소프트웨어 팀이 AI‑지원 개발에 의존할수록 이 차이는 더욱 중요해집니다.
- 인간에게, 불명확한 레포는 마찰을 일으킵니다.
- AI 에이전트에게, 위험을 초래합니다. 에이전트는 눈에 보이는 명령을 실행하고, 통과 결과를 얻은 뒤 레포가 정상이라고 가정할 수 있지만, 그 결과는 시스템의 아주 작은 부분만을 증명할 뿐입니다.
다음 표준은 단순히:
Can this repo run?이 아니라:
Can this repo be trusted when it runs?Runnable is a low bar
A repo is runnable when someone can get it to execute.
- Maybe the app starts locally.
- Maybe one test command passes.
- Maybe the build completes on a maintainer’s machine.
That is useful, but it does not answer enough questions.
A runnable repo may still leave important things unclear:
- Which runtime and tool versions were used?
- Was setup completed correctly?
- Were required services running?
- Was this a quick check or the full verification path?
- Was the command safe for automation?
- Did the result match what CI expects?
- Can someone else reproduce the same outcome?
If those answers are missing, the repo may run, but the result is difficult to interpret.
That is the gap between execution and trust.
신뢰할 수 있는 저장소는 조건을 명시합니다
신뢰할 수 있는 저장소는 명령만 제공하지 않습니다. 명령에 대한 조건을 설명합니다.
실행 가능한 예시
pytest더 신뢰할 수 있는 예시
Runtime:
Python: 3.12
Services:
- Postgres 16 must be running
Quick check:
pytest tests/unit
Full verification:
- pytest --cov
- ruff check .
- mypy .첫 번째 버전은 사람에게 무엇을 실행해야 하는지 알려줍니다.
두 번째 버전은 결과가 무엇을 의미하는지 알려줍니다.
그 차이는 중요합니다. AI 에이전트가 pytest를 실행하고 통과를 확인하면 성공을 보고할 수 있습니다. 하지만 저장소의 실제 검증 경로에 커버리지, 린팅, 타입 체크, 데이터베이스 기반 통합 테스트가 포함되어 있다면 그 성공은 불완전합니다.
- 명령이 실행되었습니다.
- 저장소는 완전히 검증되지 않았습니다.
신뢰할 수 있는 레포는 잘못된 자신감을 줄인다
불명확한 레포지토리의 위험한 점은 단순히 실패가 아니라 잘못된 자신감이다.
실패는 조사를 강제한다. 오해를 일으키는 통과는 상황이 좋지 않은데도 인간, CI 작업, 혹은 에이전트에게 상황이 괜찮다고 알려주기 때문에 더 나쁠 수 있다.
다음과 같은 경우에 발생한다:
- 로컬 검사가 CI 검사보다 약하다.
- README 명령이 오래되었다.
- 서비스 의존성이 암시적이다.
- 생성된 파일이 누락된다.
- 마이그레이션이 테스트되지 않는다.
- 안전한 명령과 위험한 명령이 혼합되어 있다.
- 에이전트가 작은 로컬 검사를 전체 검증으로 간주한다.
이러한 경우 레포는 의미 있는 확신을 제공하지 않으면서도 녹색 출력만 생성할 수 있다.
이는 단순히 테스트 문제만이 아니라 실행‑거버넌스 문제이다. 레포는 충분한 증거가 무엇인지 명확히 제시하지 않았다.
신뢰할 수 있는 저장소는 안전한 실행을 정의한다
저장소는 안전한 실행과 위험한 실행을 구분할 때 더 신뢰할 수 있게 됩니다.
보통 안전한 명령
test
lint
typecheck
build명시적인 승인이 필요한 명령
deploy
publish
db:reset
terraform apply인간에게는 경험을 통해 차이가 명확할 수 있지만, 자동화 및 AI 에이전트에게는 명시되어야 합니다.
파일에도 동일하게 적용됩니다:
- 소스 코드와 테스트 → 일반적으로 편집이 안전합니다.
- 생성된 파일, 프로덕션 설정, lockfiles, migrations, environment files → 더 강력한 검토가 필요할 수 있습니다.
신뢰할 수 있는 저장소는 에이전트가 파일 이름만으로 경계를 추측하도록 의존하지 않습니다. 안전한 경로를 명확히 표시합니다.
신뢰할 수 있는 저장소는 증거를 생성합니다
A runnable repo says:
The command ran.A trustworthy repo can say more:
- 실행된 명령
- 먼저 수행된 설정
- 예상된 환경
- 선택된 작업
- 통과 여부 또는 실패 여부
- 건너뛴 항목
- 여전히 검토가 필요한 항목
That evidence matters for humans, CI, and especially agents. When an agent reports that work is complete, the team needs to know whether it ran the right task, in the right context, with the right boundaries.
Without evidence, agent output becomes another thing to verify manually from scratch.
With evidence, automation becomes easier to trust.
계약 레이어
이곳이 바로 이 시리즈의 이전 글들이 가리키던 곳입니다.
레포가 인간, CI, 자동화, 그리고 AI 에이전트에 의해 신뢰받아야 할 때, 흩어진 지시만으로는 충분하지 않습니다. 레포에는 계약 레이어가 필요합니다: 설정, 작업, 안전 경계, 검증, 실행 기대치를 한곳에서 검토할 수 있는 선언된 장소 말이죠.
그 역할을 수행하도록 설계된 것이 Ota의 ota.yaml입니다.
중요한 변화는 “다른 설정 파일을 사용한다”가 아니라는 점입니다.
변화는 다음과 같습니다:
From:
This repo has commands you can try.
To:
This repo declares how execution should happen, what is safe, and what evidence counts.이 모델에서:
ota doctor는 작업 시작 전에 준비 상태를 확인할 수 있습니다.ota validate는 계약 자체가 유효한지 검증할 수 있습니다.ota up은 선언된 설정대로 레포를 준비할 수 있습니다.ota run은 인간이나 에이전트가 추측하지 않아도 선언된 작업을 실행할 수 있습니다.
올바른 명령 추측하기
값은 단순히 작업이 실행되는 것에만 있지 않습니다.
값은 실행이 명시적이고, 경계가 정해져 있으며, 검토 가능하게 되는 데 있습니다.
이것이 레포가 실행 가능에서 신뢰할 수 있음으로 이동하게 하는 요소입니다.
더 나은 표준
이전 표준은
Can I run this repo?더 나은 표준은
Can I trust what happened when this repo ran?이는 단일 명령만으로는 충분하지 않습니다.
다음이 필요합니다:
- 명확한 설정
- 선언된 작업
- 안전한 실행 경계
- 검증 경로
- 실제로 일어난 일에 대한 증거
AI 에이전트에게 특히 중요한데, 이들은 단순히 레포를 읽는 것이 아니라 레포 내부에서 동작하도록 점점 더 기대되고 있기 때문입니다. 에이전트는 다음을 알아야 합니다:
- 무엇이 안전한지
- 검증이란 무엇인지
- 언제 멈춰야 하는지
- 무엇을 보고해야 하는지
신뢰할 수 있는 레포는 이러한 답변을 가시화합니다.
결론
- 실행 가능한 레포는 유용하지만 반드시 신뢰할 수 있는 것은 아닙니다.
- 작은 테스트를 통과하거나 빌드가 성공한다 하더라도, 결과를 가능하게 만든 조건을 숨길 수 있습니다.
- 성공적인 녹색 출력이 나오더라도 레포가 실제로 준비되었는지를 증명하지 못하면, 인간, CI, 에이전트가 성공을 서로 다르게 해석하게 됩니다.
이 때문에 레포 준비 상태는 시작에 불과합니다.
궁극적인 목표는 실행 거버넌스입니다: 소프트웨어 실행을 명시적이고, 안전하며, 검증 가능하고, 인간, CI, 자동화, AI 에이전트가 재사용할 수 있도록 만드는 것입니다.
- 실행할 수 있는 레포는 시간을 절약합니다.
- 신뢰할 수 있는 레포는 사람과 에이전트가 보다 안전하게 작업할 수 있게 합니다.
리소스 살펴보기