코드베이스는 하네스의 일부다
AI 코딩 에이전트는 저장소를 사람처럼 읽지 않는다. 사람은 "이 문서는 예전 내용 같네", "이 위키는 이제 안 쓰겠네", "이 설정 파일은 과거 마이그레이션 잔재겠네"라고 추측한다. 에이전트는 그렇게 판단하지 못한다. README.md, 오래된 설계 문서, 주석 처리된 예제, 실패한 실험 기록, 실제 코드, 테스트, CI 설정을 모두 같은 저장소 안의 텍스트로 본다.
그래서 하네스 엔지니어링에서 코드베이스는 단순한 작업 대상이 아니다. 에이전트가 일하는 환경이며, 곧 하네스의 일부다. OpenAI는 에이전트가 저장소 자체만 보고 비즈니스 도메인을 추론할 수 있도록 만드는 것이 인간 엔지니어의 중요한 역할이라고 설명한다1. 이 말은 저장소가 에이전트에게 "무엇이 진실인지" 알려주는 인터페이스가 되어야 한다는 뜻이다.
좋은 저장소는 에이전트에게 세 가지를 준다.
어디를 읽어야 하는지
무엇을 믿어야 하는지
어떻게 스스로 검증해야 하는지
나쁜 저장소는 반대로 에이전트를 오래된 정보와 중복 패턴 속에 밀어 넣는다. 그 결과 에이전트는 틀린 설명을 근거로 코드를 만들고, 죽은 설정을 되살리고, 과거의 임시 패턴을 현재 표준처럼 복제한다.
최상위 신뢰 신호는 실행 가능한 산출물이다
저장소 안의 모든 정보가 같은 가치를 갖지는 않는다. 에이전트에게 가장 강한 신뢰 신호는 사람이 쓴 설명이 아니라 실행 가능한 산출물이어야 한다.
우선순위는 대략 다음과 같다.
코드
테스트
타입 정의
스키마
린터와 포매터 설정
CI 설정
ADR 같은 상태가 명시된 의사결정 기록
README와 설계 문서
오래된 메모, 임시 계획, 개인 노트
이 순서가 중요한 이유는 간단하다. 실행 가능한 산출물은 거짓말을 오래 하지 못한다. 타입 정의가 틀리면 빌드가 깨진다. 스키마가 맞지 않으면 검증이 실패한다. 테스트가 실제 동작과 어긋나면 빨간불이 켜진다. 린터 규칙은 매번 같은 기준으로 위반을 잡는다.
반면 "현재 인증 구조는 세션 기반이다"라는 문장은 코드가 JWT로 바뀐 뒤에도 그대로 남아 있을 수 있다. 이 문서는 사람에게도 위험하지만, 에이전트에게는 더 위험하다. 에이전트는 그 문장을 현재 사실로 받아들이고 새 코드를 세션 기반으로 작성할 수 있다.
따라서 하네스 엔지니어의 일은 "좋은 설명을 많이 쓰는 것"이 아니다. 에이전트가 실행 가능한 신호를 먼저 보게 만들고, 설명 문서는 그 신호를 보조하게 만드는 일이다.
예를 들어 다음 문서보다:
우리 프로젝트는 모든 API 응답을 표준 형식으로 반환합니다.다음 구조가 더 강하다.
export const ApiResponseSchema = z.object({
ok: z.boolean(),
data: z.unknown().optional(),
error: ErrorSchema.optional(),
});그리고 더 강한 것은 이 스키마를 테스트와 CI에서 실제로 검증하는 것이다.
문서는 지도여야지, 낡은 진실이어서는 안 된다
그렇다고 문서를 없애야 한다는 뜻은 아니다. 에이전트에게도 문서는 필요하다. 다만 문서의 역할을 바꿔야 한다. 문서는 현재 시스템을 완벽하게 설명하는 백과사전이 아니라, 검증 가능한 신호로 안내하는 지도여야 한다.
좋은 문서는 다음 네 가지를 함께 적는다.
적용 범위
최종 갱신일
검증 명령
관련 코드 경로
예시는 다음과 같다.
## 인증 토큰 처리
- 적용 범위: `src/auth/**`, `src/api/middleware/auth.ts`
- 최종 갱신일: 2026-05-10
- 관련 ADR: `docs/adr/0017-jwt-auth.md`
- 검증 명령:
- `pnpm test auth`
- `pnpm lint src/auth`
- `pnpm typecheck`
- 관련 코드:
- `src/auth/token.ts`
- `src/auth/session-store.ts`는 Deprecated 상태이며 신규 코드에서 사용 금지이 형식은 에이전트에게 중요한 단서를 준다. "이 문서가 어디까지 적용되는가", "얼마나 최근 정보인가", "설명이 맞는지 어떻게 확인하는가", "실제 코드는 어디에 있는가"를 알 수 있다.
반대로 다음과 같은 문서는 위험하다.
현재 시스템은 대체로 auth 모듈에서 인증을 처리한다.
예전에는 session-store를 썼지만 지금은 조금 바뀌었다.
자세한 내용은 코드 참고.사람도 헷갈리고 에이전트도 헷갈린다. 문서는 짧아도 된다. 하지만 범위와 검증 방법은 명확해야 한다.
ADR은 과거와 현재를 분리하는 장치다
아키텍처 결정 기록, 즉 ADR은 에이전트 친화적 저장소에서 특히 중요하다. 이유는 ADR이 "그때 왜 그렇게 결정했는가"를 기록하기 때문이다. 코드만 보면 현재 상태는 알 수 있지만, 대안과 배경은 보이지 않는다.
문제는 오래된 결정이다. 과거에는 맞았지만 지금은 틀린 결정이 저장소에 남아 있을 수 있다. 그래서 ADR에는 반드시 상태가 있어야 한다.
권장 상태는 다음과 같다.
Proposed: 제안됨Accepted: 현재 기준으로 채택됨Superseded: 다른 결정으로 대체됨Deprecated: 더 이상 권장되지 않음
대체된 ADR에는 새 ADR 링크와 영향받는 모듈을 적는다.
# JWT 기반 인증으로 전환
- 상태: Superseded
- 작성일: 2025-11-03
- 대체 ADR: `docs/adr/0024-token-rotation.md`
- 영향받는 모듈:
- `src/auth/**`
- `src/api/middleware/**`
## 결정
초기에는 단일 JWT 액세스 토큰만 사용한다.
## 현재 상태
이 결정은 2026-04-18에 `0024-token-rotation.md`로 대체되었다.
신규 코드는 refresh token rotation 정책을 따라야 한다.이렇게 하면 에이전트가 grep으로 오래된 ADR을 발견하더라도 상태를 보고 현재 기준이 아님을 알 수 있다. ADR은 수정해서 과거를 지우는 문서가 아니다. 새 결정으로 대체하면서 역사를 남기는 문서다. 이 차이가 에이전트에게 과거 맥락과 현재 기준을 구분하게 해준다.
AGENTS.md에는 반복 규칙만 담는다
최근 여러 도구는 AGENTS.md, CLAUDE.md, agent.md, .cursor/rules 같은 저장소 로컬 지시 파일을 사용한다. 특히 AGENTS.md는 README가 사람을 위한 문서라면, 에이전트를 위한 운영 지침이라는 관점으로 확산되고 있다2.
이 파일에는 많이 쓰는 규칙을 넣어야 한다. 그러나 모든 것을 넣으면 안 된다. 길고 장황한 지시 파일은 컨텍스트를 잡아먹고, 중요한 규칙을 묻어버린다.
넣어야 할 내용은 다음과 같다.
프로젝트 한 줄 설명
빌드 명령
테스트 명령
린트와 포맷 명령
단일 파일 또는 단일 모듈 테스트 방법
코드 스타일 중 기계적으로 강제되지 않는 것
금지된 변경
리뷰 체크리스트
안전 경계
더 깊은 문서로 가는 링크
넣지 말아야 할 내용도 있다.
일회성 작업 계획
개인 취향
이미 코드나 린터로 표현된 중복 설명
오래된 마이그레이션 노트
모든 디렉터리를 장황하게 설명하는 문단
에이전트가 코드에서 쉽게 추론할 수 있는 내용
좋은 AGENTS.md는 매뉴얼이 아니라 목차에 가깝다.
## 필수 명령
- 설치: `pnpm install`
- 타입 체크: `pnpm typecheck`
- 린트: `pnpm lint`
- 전체 테스트: `pnpm test`
- 인증 모듈 테스트: `pnpm test auth`
## 작업 규칙
- 구현 전 관련 테스트를 먼저 확인한다.
- 신규 API 응답은 `src/contracts/api-response.ts`의 스키마를 사용한다.
- `src/domain/**`에서는 DB 클라이언트를 import하지 않는다.
- 완료 전 `pnpm typecheck && pnpm lint && pnpm test`를 실행한다.
## 더 읽을 문서
- 아키텍처 결정: `docs/adr/`
- 모듈 경계: `docs/architecture/module-boundaries.md`
- 자주 틀리는 패턴: `docs/gotchas.md`핵심은 반복성이다. 여러 세션에서 계속 필요한 규칙이면 지시 파일에 넣는다. 한 번 쓰고 버릴 계획이면 작업 이슈나 별도 계획 파일에 둔다.
컨텍스트를 오염시키는 저장소 쓰레기
저장소 위생이 나빠지면 에이전트의 컨텍스트가 오염된다. 오염된 컨텍스트는 성능 문제이자 품질 문제다. 에이전트는 불필요한 정보를 읽느라 토큰을 쓰고, 오래된 패턴을 현재 표준으로 착각한다. 에이전트 친화적 코드베이스를 다룬 실무 글들도 명확한 구조, 검증 가능한 명령, 문서화된 도메인 지식이 에이전트 품질을 크게 좌우한다고 강조한다3.
대표적인 오염원은 다음과 같다.
첫째, 현재 구조를 장황하게 설명하는 문서다. 이런 문서는 작성 직후에는 유용하지만 코드가 바뀌는 순간 부패한다. 구조 설명이 필요하다면 자동 생성 가능한 다이어그램, 실제 경로, 검증 명령과 함께 유지해야 한다.
둘째, 중복된 예제다. 예제가 두 개이고 서로 다른 패턴을 쓰면 에이전트는 둘 중 아무거나 따라 할 수 있다. 예제는 하나의 골든 패스로 줄이는 편이 낫다.
셋째, 죽은 설정이다. 더 이상 쓰지 않는 ESLint 설정, 예전 CI 파일, 사용하지 않는 Docker Compose 파일은 에이전트에게 "이 프로젝트는 이것도 지원한다"는 잘못된 신호를 준다.
넷째, 사용되지 않는 패턴이다. 예전 레이어 구조, 폐기된 API 클라이언트, 임시 유틸리티가 남아 있으면 에이전트는 그것을 복제한다. 에이전트는 저장소에 이미 있는 패턴을 강하게 따른다. 좋은 패턴도 복제하지만 나쁜 패턴도 복제한다.
다섯째, 주석 처리된 코드다. 사람은 "나중에 참고하려고 남겼구나"라고 생각할 수 있다. 에이전트는 이를 구현 후보로 볼 수 있다. 필요 없다면 삭제하고, 필요하면 테스트 가능한 코드나 명시적 문서로 옮겨야 한다.
저장소 위생 점검을 반복 작업으로 만든다
저장소 위생은 한 번 정리하고 끝나는 일이 아니다. 코드가 바뀌면 문서는 늦고, 설정은 남고, 예제는 갈라진다. 그래서 정기적인 "쓰레기 수집" 태스크가 필요하다.
작게 시작해도 된다.
매주 오래된 문서 3개 점검
Deprecated표시가 있는 파일 삭제 가능 여부 확인사용하지 않는 의존성 탐지
실패하거나 느린 테스트 분류
중복 예제 제거
AGENTS.md와 실제 명령 불일치 확인ADR 상태 누락 확인
가능하면 이 작업도 자동화한다. GitHub는 에이전트가 이슈 분류, 문서 갱신, 테스트 개선, CI 실패 조사 같은 반복 저장소 작업을 수행하는 "Agentic Workflows"를 소개하며, 이런 자동화가 기존 CI/CD를 대체하는 것이 아니라 보완한다고 설명한다4. 즉, 에이전트에게 저장소를 고치게 할 수도 있다. 다만 이때도 기준은 결정론적이어야 한다.
"낡아 보이는 문서를 알아서 판단해서 지워라"는 위험하다. 대신 다음처럼 말해야 한다.
다음 조건을 만족하는 문서만 PR로 표시한다.
- 최종 갱신일이 180일 이상 지남
- 관련 코드 경로가 존재하지 않음
- 검증 명령이 실패함
- 대체 문서 또는 ADR 링크가 있음
삭제하지 말고 `Deprecated` 상태 표시와 근거를 포함한 PR을 연다.에이전트에게 판단을 맡기되, 판단 기준은 저장소 안의 기계적 신호에 묶어야 한다.
저장소 위생의 목표
저장소 위생의 목표는 깨끗해 보이는 저장소가 아니다. 에이전트가 신뢰할 수 있는 신호를 빠르게 찾는 저장소다.
이를 위해 기억할 원칙은 다섯 가지다.
실행 가능한 산출물을 최상위 신뢰 신호로 둔다.
문서는 적용 범위, 갱신일, 검증 명령, 관련 코드 경로를 포함한다.
ADR은 상태와 대체 관계를 명확히 기록한다.
AGENTS.md에는 반복 가능한 운영 규칙만 담는다.오래된 문서, 죽은 설정, 중복 예제는 정기적으로 삭제하거나 상태를 표시한다.
에이전트는 우리가 남긴 흔적을 따라 일한다. 저장소가 모호하면 결과도 모호하다. 저장소가 검증 가능하면 에이전트도 스스로 검증할 수 있다. 결국 에이전트 친화적 코드베이스는 사람에게도 좋은 코드베이스다. 차이는 하나다. 사람은 혼란을 참아낼 수 있지만, 에이전트는 그 혼란을 증폭한다.
참고
1Harness engineering: leveraging Codex in an agent-first world
2The Agent-Native Repo: Why AGENTS.MD is the New Standard
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.