에이전트에게 필요한 것은 더 나은 모델만이 아닙니다. 더 나은 레포지토리(Repository)가 필요합니다.

코딩 에이전트에 관한 대부분의 대화는 결국 모델 비교로 귀결됩니다.

어떤 모델이 더 나은가?
어떤 모델이 더 깔끔한 코드를 작성하는가?
어떤 모델이 지시사항을 더 잘 따르는가?
어떤 모델이 더 큰 레포지토리(Repository)를 다룰 수 있는가?

이러한 질문들은 중요합니다.

하지만 코딩 에이전트를 사용하면 사용할수록, 저는 우리가 문제의 더 큰 부분을 놓치고 있다는 생각이 듭니다.

에이전트는 모델이 나빠서가 아니라, 레포지토리(Repository)가 에이전트에게 적합하지 않아서 실패하는 경우가 많습니다.

코딩 에이전트는 깨끗하고 추상적인 문제 공간에 착륙하는 것이 아닙니다.

에이전트는 당신의 레포지토리(Repository)에 착륙합니다.

그리고 당신의 레포지토리(Repository)는 프롬프트(Prompt)의 일부입니다.

레포지토리(Repository)는 프롬프트(Prompt)의 일부입니다

에이전트가 코드베이스(Codebase)에서 작업을 시작할 때, 에이전트는 주변의 모든 것을 상속받습니다.

폴더 구조를 상속받습니다.

명명 규칙(Naming conventions)을 상속받습니다.

누락된 문서(Docs)를 상속받습니다.

오래된 설정 지침(Setup instructions)을 상속받습니다.

실행될 수도 있고 되지 않을 수도 있는 테스트 스위트(Test suite)를 상속받습니다.

팀 내의 몇 명만이 이해하는 내부 패턴을 상속받습니다.

이상한 설정 파일(Config files)을 상속받습니다.

시간이 흐르며 축적된 지름길, 불일치, 그리고 절반만 작성된 결정 사항들을 상속받습니다.

그러고 나서 우리는 에이전트에게 안전한 변경을 수행하라고 요청합니다.

그리고 에이전트가 무언가 잘못했을 때, 우리는 모델을 비난합니다.

때로는 그것이 타당할 수도 있습니다. 때로는 모델이 정말로 요점을 놓치기도 합니다.

하지만 종종, 레포지토리(Repository)가 에이전트에게 작업하기 나쁜 환경을 제공했을 뿐입니다.

“모델이 나빴다”는 때때로 잘못된 진단입니다

저는 처음에는 지능 문제처럼 보이는 방식으로 에이전트가 실패하는 것을 보았습니다.

예를 들어:

• 너무 많은 코드를 재작성합니다.
• 프로젝트 관례(Project convention)를 무시합니다.
• 팀이 절대 승인하지 않을 의존성(Dependency)을 추가합니다.
• 테스트를 어떻게 실행해야 하는지 파악하지 못합니다.
• 아마도 피해야 할 파일들을 건드립니다.
• 오래된 설정 지침(Setup instructions)을 따릅니다.
• 그럴듯해 보이지만 레포지토리(Repository)의 작동 방식과 일치하지 않는 변경을 수행합니다.

이것을 모델의 실패라고 부르기는 쉽습니다.

하지만 만약 인간 엔지니어가 온보딩 문서(onboarding doc), 아키텍처 노트(architecture notes), 기여 가이드(contribution guide), 명확한 테스트 명령(test command), 그리고 팀의 컨벤션(conventions)에 대한 설명도 없이 동일한 프로젝트에 합류했다면, 우리는 그 엔지니어가 첫날부터 실력이 없다고 말하지 않을 것입니다.

우리는 레포지토리(Repository)의 온보딩(onboarding)이 부실하다고 말할 것입니다.

에이전트(Agents)도 똑같은 문제를 겪습니다.

단지 그들은 더 빠르게 실패할 뿐입니다.

그리고 더 큰 확신을 가지고 실패합니다.

좋은 에이전트 워크플로우(Workflow)는 지루합니다

제가 본 최고의 코딩 에이전트(coding-agent) 워크플로우는 마법 같지 않습니다.

그것들은 대개 매우 유용한 방식으로 지루합니다.

레포지토리(Repository)에는 다음과 같은 것들이 있습니다:

• 명확한 AGENTS.md 또는 그에 상응하는 지침 파일(instruction file)
• 문서화된 설정 단계(setup steps)
• 고정된 도구(tools) 및 버전(versions)
• 명확한 테스트 명령(test commands)
• 유용한 피드백을 제공하는 CI(지속적 통합)
• 명확한 프로젝트 컨벤션(project conventions)
• 비밀 정보(secrets) 및 설정(config)에 대한 안전한 경계
• 에이전트가 무엇이 "좋은" 상태인지 이해할 수 있는 충분한 컨텍스트(context)

그것이 에이전트를 완벽하게 만들어주지는 않습니다.

하지만 실패 모드(failure mode)를 바꿉니다.

에이전트는 무모하게 추측하는 대신 가이드라인(rails)을 갖게 됩니다. 에이전트는 제한된 범위 내에서 변경(bounded change)을 수행하고, 예상되는 체크(checks)를 실행하며, 자신이 무엇을 했는지 설명할 수 있습니다.

이는 "여기에 모호한 작업이 있으니, 당신이 거의 이해하지 못하는 레포지토리를 수정해 주세요"라는 방식과는 매우 다른 워크플로우입니다.

레포지토리 준비도(Repo readiness)는 측정 가능해야 합니다

우리는 이미 소프트웨어 품질의 많은 부분을 측정하고 있습니다.

우리는 테스트 커버리지(test coverage)를 측정합니다.

우리는 린트 에러(lint errors)를 측정합니다.

우리는 빌드 상태(build status)를 측정합니다.

우리는 의존성(dependencies)을 스캔합니다.

우리는 비밀 정보(secrets)를 확인합니다.

우리는 CI 상태(CI health)를 추적합니다.

하지만 코딩 에이전트(coding agents)에 관해서라면, 우리는 여전히 모호한 언어를 사용합니다:

이 레포지토리는 에이전트와 꽤 잘 작동합니다.

Claude Code는 여기서 고전합니다.

Codex는 계속 이상한 변경을 수행합니다.

Cursor는 이 레포지토리에서는 좋지만 저 레포지토리에서는 나쁩니다.

그러한 관찰은 유용하지만, 운영적(operational)이지는 않습니다.

에이전트가 실제 레포지토리 내부에서 작동하려면, 우리는 더 나은 질문이 필요합니다:

• 레포지토리가 자체적인 컨벤션 (Conventions)을 설명하고 있는가?
• 에이전트가 올바른 설정 경로 (Setup path)를 찾을 수 있는가?
• 도구 버전이 고정 (Pinned)되어 있는가?
• 테스트 명령어를 발견할 수 있는가?
• 위험한 명령어가 문서화되어 있거나 격리되어 있는가?
• 비밀 정보 (Secrets)가 무심코 읽히지 않도록 보호되고 있는가?
• 광범위한 추측을 피할 수 있을 만큼 충분한 프로젝트 컨텍스트 (Context)가 있는가?
• 레포지토리가 변경됨에 따라 이를 반복적으로 확인할 수 있는가?

마지막 질문이 중요합니다.

에이전트 준비성 (Agent-readiness)은 일회성 정리 작업이 되어서는 안 됩니다. 다른 모든 것과 마찬가지로 개선되고, 퇴보할 수도 있으며, CI (지속적 통합)에서 확인될 수 있는 것이어야 합니다.

이것은 엔지니어를 대체하는 것에 관한 것이 아닙니다

저는 실질적인 미래가 "에이전트가 모든 것을 수행하고 엔지니어는 사라진다"는 것이라고 생각하지 않습니다.

더 유용한 버전은 다음과 같습니다:

에이전트가 엔지니어링 워크플로 (Workflow)의 일부가 되는 것입니다.

에이전트는 리팩터링 (Refactors), 테스트, 문서화, 마이그레이션 (Migrations), 조사, 반복적인 변경, 그리고 구현 작업 (Implementation work)을 돕습니다.

하지만 에이전트가 워크플로의 일부가 되려면, 그 워크플로는 에이전트를 위해 설계되어야 합니다.

오늘날 대부분의 레포지토리는 여전히 이미 컨텍스트를 가지고 있는 인간을 위해 설계되어 있습니다.

인간은 Slack 히스토리, 팀의 기억, 온보딩 (Onboarding) 미팅, 제품 지식, 그리고 수년간 축적된 판단력을 가지고 있습니다.

에이전트는 우리가 에이전트가 사용할 수 있는 어딘가에 기록해 두지 않는 한, 그런 것들을 가지고 있지 않습니다.

즉, 레포지토리가 자체적인 컨텍스트를 더 많이 담고 있어야 한다는 의미입니다.

개발자 도구의 다음 계층

저는 이것이 많은 개발자 도구가 나아가는 방향이라고 생각합니다.

단순히 더 나은 채팅 인터페이스가 아닙니다.

단순히 더 나은 에디터가 아닙니다.

단순히 더 큰 컨텍스트 윈도우 (Context windows)가 아닙니다.

에이전트 중심의 작업 (Agentic work)을 위해 코드베이스를 더 안전하고 이해하기 쉽게 만드는 레포지토리 수준의 시스템입니다.

그것은 다음과 같은 것을 의미합니다:

• 더 명확한 지침
• 더 나은 기본값 (Defaults)
• 결정론적 체크 (Deterministic checks)
• 더 안전한 자동화 경계
• 더 나은 CI 통합
• 에이전트가 할 수 있는 일과 할 수 없는 일에 대한 더 명시적인 거버넌스 (Governance)

이것은 또한 제가 Charter라는 작은 오픈 소스 프로젝트를 통해 탐구해 온 아이디어이기도 합니다.

Charter는 코딩 에이전트 (coding-agent) 워크플로우를 위해 레포지토리 (repository)에 결정론적인 0–100 준비도 점수 (readiness score)를 부여하는 오프라인 CLI (Command Line Interface)입니다.

다음과 같은 영역을 점검합니다:

• 컨텍스트 (Context)
• 비밀 정보 (Secrets)
• MCP/도구 안전성 (tool safety)
• 환경 설정 (Environment setup)
• CI (Continuous Integration)
• 테스트 (Tests)
• 거버넌스 (Governance)

그 후, 에이전트가 실패할 가능성을 높이는 구체적인 격차 (gaps)를 지적합니다.

LLM 점수 산정 없음.
네트워크 호출 없음.
동일한 레포지토리, 동일한 점수.

프로젝트는 아직 초기 단계이지만, 다음과 같은 프레임워크 (framing)가 저에게 유용했습니다:

만약 에이전트가 특정 레포지토리에서 계속 실패한다면, 어쩌면 레포지토리 자체가 문제의 일부일 수도 있습니다.

GitHub: https://github.com/use-charter/charter

마지막 생각

더 나은 모델이 도움이 될 것입니다.

모델은 더 잘 추론할 것입니다. 지시 사항을 더 잘 따를 것입니다. 실수를 더 적게 할 것입니다.

하지만 모델은 여전히 우리가 제공하는 환경을 물려받게 됩니다.

만약 레포지토리가 혼란스럽고, 안전하지 않으며, 문서화가 되어 있지 않고, 검증하기 어렵다면, 매우 뛰어난 에이전트라 할지라도 상황을 더 악화시킬 수 있습니다.

모델도 중요합니다.

레포지토리 또한 중요합니다.