로컬, CI, 그리고 에이전트 실행을 일치시키는 방법

개요 (Overview)

레포지토리(repo)를 신뢰할 수 없게 만드는 가장 빠른 방법 중 하나는 로컬 개발, CI, 그리고 에이전트(agent) 실행이 서로 세 가지 다른 이야기로 어긋나게 방치하는 것입니다.

개발자는 로컬에서 하나의 명령어를 실행합니다. CI는 다른 환경에서 더 엄격한 경로를 실행합니다. 에이전트는 README를 읽고, 패키지 스크립트(package scripts)를 확인하고, 워크플로(workflow) 파일을 열어보며, 레포지토리의 어떤 버전이 실제로 진실인지 추측해야만 합니다.

바로 이 지점에서 잘못된 자동화가 시작됩니다.

코드는 괜찮을 수 있습니다. 실패는 종종 운영상의 문제입니다. 레포지토리가 인간, CI, 그리고 에이전트가 동일한 로직을 따를 수 있도록 의도된 실행 경로를 충분히 명확하게 제시하지 못했기 때문입니다.

드리프트(Drift)는 조용히 시작된다

실행 드리프트(Execution drift)는 보통 거대한 설계 결정으로 인해 발생하지 않습니다. 그것은 편의성에서 비롯되어 자라납니다.

프로젝트는 다음과 같이 단순하게 시작됩니다:

npm test

나중에 CI가 더 엄격해집니다:

pnpm install --frozen-lockfile
pnpm lint
pnpm typecheck
...

그 후 레포지토리가 다시 성장합니다. 서비스가 Docker로 이동합니다. 통합 테스트(Integration tests)에는 Postgres가 필요합니다. 새로운 환경 변수(environment variable)가 나타납니다. README는 포괄적인 상태로 남아 있고, CI는 전체 경로를 가진 유일한 장소가 되며, 로컬 스크립트는 이야기의 일부만을 설명합니다.

이제 레포지토리는 운영상의 진실(operational truth)에 대한 여러 소스를 갖게 됩니다.

인간은 이를 "내 컴퓨터에서는 잘 되는데"라고 느낍니다. 에이전트는 이를 상충하는 신호로 느낍니다. 에이전트는 가장 명백한 명령어를 실행하여 부분적인 통과를 얻고, CI에서는 여전히 실패할 레포지토리에 대해 성공을 보고합니다.

이것은 항상 에이전트의 추론 실패 때문만은 아닙니다. 많은 경우, 레포지토리가 불완전한 지침을 제공했기 때문입니다.

일치(Alignment)가 동일한 명령어를 의미하는 것은 아니다

일치(Alignment)가 로컬 개발, CI, 그리고 에이전트가 정확히 동일한 명령어 시퀀스를 실행해야 함을 의미하지는 않습니다.

로컬 워크플로(Local workflows)는 빠르게 유지될 수 있습니다. CI는 엄격하게 유지될 수 있습니다. 에이전트는 유지 관리자(maintainer)보다 더 타이트한 안전 경계(safety boundaries)를 가질 수 있습니다.

일치되어야 하는 것은 의도(intent)입니다.

Local:
개발 전후 및 개발 중에 빠른 체크를 실행합니다.

...

문제는 각 경로가 동일한 운영 모델(operating model)로부터 선언되는 대신, 각각 별도로 만들어질 때 시작됩니다.

무엇을 먼저 일치시켜야 하는가

가장 좋은 시작점은 가장 많은 혼란과 잘못된 확신(false confidence)을 주는 리포지토리(repo)의 부분들부터 시작하는 것입니다.

1. 설정 (Setup)

리포지토리에는 하나의 명확한 설정 경로가 있어야 합니다.

Python 서비스의 경우, 다음과 같을 수 있습니다:

poetry install
docker compose up -d postgres
poetry run alembic upgrade head

Go 서비스의 경우, 다음과 같을 수 있습니다:

go mod download
docker compose up -d redis
go test ./...

기술 스택(stack)이 핵심이 아닙니다. 명확함(Clarity)이 핵심입니다. 설정은 README의 설명글, CI YAML, 셸 히스토리(shell history), 그리고 팀 동료 한 명의 기억 속에 분산되어 있어서는 안 됩니다.

2. 작업 (Tasks)

리포지토리는 명확한 이름을 가진 공통 작업들을 노출해야 합니다.

setup
test
test:integration
...

작업 이름이 의도(intent)를 설명할 때 사람과 에이전트(agent) 모두 더 잘 작동합니다. 만약 누군가가 무엇이 빠르고, 완전하며, 안전한지, 혹은 파괴적인지를 파악하기 위해 모든 스크립트를 일일이 검사해야 한다면, 그 리포지토리는 이미 너무 모호한 상태입니다.

3. 검증 (Verification)

검증은 드리프트(drift)가 비용이 많이 들게 되는 지점입니다.

리포지토리는 빠른 피드백과 전체 검증을 분리해야 합니다:

Quick check:
pytest tests/unit

...

그러한 구분이 없다면, 기여자들은 빠른 확인 단계에서 멈추고 작업이 완료되었다고 가정하게 되며, 그 사이 CI는 여전히 실제 표준을 유지하고 있게 됩니다.

4. 서비스 (Services)

서비스는 결코 암시되어서는 안 됩니다.

만약 특정 작업에 Postgres, Redis, Elasticsearch, 큐(queue), 또는 로컬 에뮬레이터(emulator)가 필요하다면, 리포지토리는 이를 직접적으로 명시해야 합니다. 또한 해당 서비스가 Docker Compose로 시작되는지, 호스트 머신(host machine)에서 제공될 것으로 예상되는지, 아니면 다른 곳에서 제공되는지도 명시해야 합니다.

이것이 중요한 이유는 누락된 서비스가 종종 애플리케이션 버그처럼 보이기 때문입니다. 실제 문제는 리포지토리가 의존성(dependencies)을 명확하게 선언하지 않은 것인데, 에이전트는 잘못된 문제를 쫓느라 시간을 허비할 수 있습니다.

5. 안전 경계 (Safety Boundaries)

에이전트에게는 실행해도 안전한 것과 검토(review)가 필요한 것 사이의 깨끗한 경계선이 필요합니다.

안전한 작업은 보통 다음과 같습니다:

test
lint
typecheck
...

위험도가 높은 작업은 보통 다음과 같습니다:

deploy
publish
db:reset
...

만약 그 경계가 명시적이지 않다면, 에이전트(agent)는 명령(command)의 이름으로부터 안전성을 추론해야 하는 상황에 놓이게 됩니다. 이는 심각한 운영 모델(operating model)이 아닙니다.

Ota의 역할

이것이 바로 Ota가 해결하고자 하는 문제입니다.

Ota는 저장소(repo) 실행을 흩어진 명령들의 집합에서 선언된 계약(declared contract)으로 전환합니다. README, 스크립트, 그리고 CI(지속적 통합)가 우연히 일치하기를 바라는 대신, 저장소는 ota.yaml에 자신의 준비 모델(readiness model)을 기술할 수 있습니다.

그 계약은 다음과 같은 사항을 선언할 수 있습니다:

• 저장소에 무엇이 필요한지
• 설정(setup)이 어떻게 이루어지는지
• 어떤 작업(task)들이 존재하는지
• 어떤 워크플로우(workflow)가 예상되는지
• 무엇을 준비 완료(readiness)로 간주할 것인지
• 어떤 명령이 에이전트에게 안전한지

Ota의 가치는 단순히 명령을 실행할 수 있다는 점에 있지 않습니다. 그 가치는 인간, CI, 그리고 에이전트가 모두 동일하게 선언된 경로(declared path)를 바탕으로 작동할 수 있다는 점에 있습니다.

예를 들어:

• ota doctor는 저장소가 실제로 준비되었는지 확인하고 방해 요소를 지적합니다.
• ota validate는 계약이 유효한지 확인합니다.
• ota up은 선언된 계약에 따라 저장소를 준비합니다.
• ota run <task>는 사람이나 에이전트가 올바른 명령을 역공학(reverse-engineer)하도록 강요하는 대신, 선언된 작업을 실행합니다.

README는 여전히 프로젝트를 설명할 수 있습니다. CI는 여전히 표준을 강제할 수 있습니다. Ota는 이들에게 공유된 실행 계약(execution contract)을 제공하여, 이들이 서로 어긋나는 것을 방지합니다.

간단한 정렬(Alignment) 체크

README에 설정 관련 설명을 더 추가하기 전에, 다음과 같은 질문을 던져볼 가치가 있습니다:

새로운 기여자가 올바른 설정 경로를 찾을 수 있는가?
CI가 저장소가 사람들에게 실행하라고 알려주는 것과 동일한 핵심 작업들을 증명하는가?
빠른 확인(quick checks)과 전체 검증(full verification) 사이의 차이가 명시적인가?
...

만약 대답이 '아니오'라면, 저장소에 필요한 것은 단순히 더 많은 문서가 아닙니다. 더 나은 정렬(alignment)이 필요합니다.

마치며

로컬 개발, CI, 그리고 AI 에이전트는 보통 똑같이 지루한 이유로 실패합니다. 저장소가 의도한 실행 경로를 충분히 명시적으로 만들지 않았기 때문입니다.

팀이 자동화와 AI 지원 개발에 더 많이 의존할수록, 이 문제는 점점 더 비용이 많이 들게 됩니다.

준비된 저장소는 인간에게는 무엇을 실행할지, CI에게는 무엇을 강제할지, 그리고 에이전트에게는 무엇이 안전한지를 알려주어야 합니다.

그것이 바로 정렬(alignment)입니다.

동일한 환경을 만드는 것이 아닙니다.

공유된 경로입니다.

계속 읽기

• AI 에이전트를 위한 리포지토리 준비 상태: 완전 가이드 (Repo Readiness for AI Agents: The Complete Guide)를 확인해 보세요.
• Ota 시작하기 (Ota getting started) 가이드를 살펴보세요.
• 실질적인 계약 (contract) 예시를 보려면 Ota 예제 리포지토리 (Ota examples repo)를 확인하세요.

원문 게시글: https://ota.run/blog/how-to-align-local-ci-and-agent-execution