에이전트 결과가 들쭉날쭉하면 모델보다 저장소를 먼저 봅니다, Factory 소프트웨어 팩토리 발표를 따라 해커톤 저장소에 AGENTS.md 한 장을 둡니다 | DAKER 커뮤니티

코딩 에이전트가 같은 저장소에서 어떤 날은 잘하고 어떤 날은 헤맨다면, 모델을 바꾸기 전에 저장소부터 점검하는 편이 빠릅니다. AI Engineer 채널이 10월 7일 공개한 Factory의 Davis Palmie 발표 「The Software Factory: From Bug Report to Production Code」는 에이전트를 시스템으로 묶는 이야기를 하면서도, 출발점은 저장소가 에이전트를 받아들일 준비가 됐는지 확인하는 일이라고 정리합니다. 해커톤 팀이 오늘 바로 할 수 있는 일은 저장소 루트에 설치·실행·테스트 명령을 적은 AGENTS.md 한 장을 두는 것입니다.

밝은 벽 앞 원목 서랍장의 열린 서랍에 공구가 가지런히 정리돼 있고 옆에 빈 체크리스트 클립보드가 놓인 실사풍 생성 이미지와 제목 문구 모델보다 저장소부터, 에이전트 준비도를 점검합니다, DAKER와 Factory 공식 로고
설명용 생성 이미지입니다.

Factory 발표의 결론: 코드를 쓰는 일은 병목이 아니었습니다

Factory 소프트웨어 팩토리 발표는 약 18분 분량이며, 2026년 AI Engineer World's Fair(샌프란시스코)에서 녹화됐습니다. Davis Palmie는 AI 코딩 도구가 세 단계를 거쳤다고 설명합니다. 처음에는 다음 토큰을 채워 주는 자동완성이었고, 다음에는 파일 전체를 만들어 주는 생성 단계였으며, 지금은 맥락을 스스로 모으고 도구를 호출하며 자기 출력을 디버깅하는 에이전트 단계입니다. 발표자는 그다음 단계로 여러 에이전트를 하나의 시스템으로 묶는 소프트웨어 팩토리를 제시합니다.

그런데 발표의 무게중심은 자동화 범위가 아니라 병목의 위치에 있습니다. 발표자는 PR 리뷰에 걸리는 중간값 시간, 사용자 버그 신고를 재현하는 시간, PR마다 문서를 최신으로 맞추는 사람, 테스트 묶음을 관리하는 사람을 차례로 묻습니다. 코드를 작성한 시점부터 운영 배포까지 걸리는 시간이 실제 코드 수정 시간보다 훨씬 길 것이라는 지적입니다.

코딩은 쉬운 부분이었고, 처음부터 병목이 아니었습니다. 발표자가 강조한 문장을 옮긴 것입니다.

해커톤으로 옮기면 의미가 분명해집니다. 대회 기간에 시간을 잡아먹는 일은 모델이 코드를 못 써서가 아니라, 팀원마다 실행 방법이 다르고 테스트가 없어 결과를 믿을 수 없고 제출 직전에 환경이 깨지는 데서 생기는 경우가 적지 않습니다. 에이전트를 붙이면 이 문제가 줄어드는 것이 아니라 더 자주, 더 빠르게 드러납니다.

소프트웨어 팩토리는 신호에서 배포까지 이어지는 에이전트 묶음입니다

발표가 정의하는 소프트웨어 팩토리는 버그 신고나 사용자 피드백 같은 입력 신호를 받아 운영 코드로 내보내는 에이전트 시스템입니다. 이 시스템 안에서 에이전트는 장애 분류, 계획 수립, 문서 작성과 갱신, 코드 실행, 리뷰, 테스트, 배포, 배포 후 모니터링까지 맡습니다. 엔지니어의 역할은 코드를 직접 치는 일에서 가드레일을 관리하고 코드 표류를 잡아내며 우선순위를 정하는 일로 옮겨 갑니다.

중요한 대목은 한꺼번에 전부 자동화하지 말라는 조언입니다. 발표자는 범위가 좁고 결과를 검증할 수 있는 일부터 시작하라고 권합니다. 예로 든 것은 장애 분류입니다. 에이전트가 Sentry 알림을 읽고 관련 트레이스와 맥락을 모아 진단을 Slack에 올리되, 무엇을 할지는 엔지니어가 검토해 결정합니다. 진단이 맞는 사례가 쌓이면서 팀이 그 단계를 신뢰하게 되고, 각 단계에 담당자와 모니터링이 자리 잡은 뒤에야 파이프라인을 순환 구조로 만들 수 있다는 설명입니다.

각 단계는 파이프라인을 순환시키기 전에 신중한 담당자 지정과 모니터링이 필요합니다.

해커톤 팀에게 이 조언은 에이전트에게 처음부터 기능 전체를 맡기지 말고, 실패한 테스트 하나를 고치거나 데이터 로더 버그 하나를 재현하는 식의 작은 일부터 맡기라는 뜻으로 읽힙니다. 결과가 테스트 통과 여부처럼 분명하게 확인되는 일이어야 에이전트가 맞았는지 틀렸는지 판단할 수 있습니다.

Factory가 꼽은 에이전트 준비도 기준은 저장소 환경을 봅니다

발표 후반부는 Factory가 에이전트 준비도(Agent Readiness)라고 부르는 평가 틀을 소개합니다. 발표에서는 여덟 가지 기둥으로 설명했고, Factory 공식 문서의 현재 버전은 이를 아홉 가지 기술 기둥으로 정리하고 있습니다. 2026년 1월 20일 Factory 공지는 이 평가의 출발점을 이렇게 설명합니다. 에이전트 결과가 들쭉날쭉할 때 팀은 모델을 탓하고 다른 에이전트를 써 보지만 결과가 같으며, 진짜 문제는 대개 코드베이스 자체라는 것입니다.

에이전트가 고장 난 것이 아니라 환경이 고장 난 것입니다. Factory 공지의 문장을 옮긴 것입니다.

Factory 공지가 든 예시는 구체적입니다. pre-commit 훅이 없으면 에이전트는 5초면 받을 피드백을 CI에서 10분 동안 기다립니다. 환경 변수가 문서화되어 있지 않으면 에이전트는 추측하고 실패하고 다시 추측합니다. 빌드 방법이 Slack 대화 속 암묵지에만 있으면 에이전트는 자기 작업을 검증할 방법을 모릅니다.

공식 문서 기준으로 기둥별로 확인하는 항목과 해커톤 저장소에서 대응하는 예를 정리하면 다음과 같습니다.

기둥Factory 문서의 예시 기준해커톤 저장소에서 볼 것
Style & Validation린터, 타입 검사기, 포매터, pre-commit 훅ruff나 black 설정이 있고 커밋 전에 돌아가는지
Build System빌드 명령 문서화, 의존성 버전 고정requirements 파일에 버전이 고정돼 있는지
Testing단위·통합 테스트 존재, 로컬에서 실행 가능제출 파일 형식을 검사하는 테스트 하나라도 있는지
DocumentationAGENTS.md, README, 문서 최신성설치·실행·테스트 명령이 적혀 있는지
Development Environmentdevcontainer, 환경 템플릿.env 예시 파일과 파이썬 버전이 정해져 있는지
Debugging & Observability구조화 로깅, 트레이싱, 지표 수집학습·추론 로그가 파일로 남는지
Security브랜치 보호, 비밀 정보 스캔, CODEOWNERSAPI 키가 저장소에 올라가지 않았는지
Task Discovery이슈 템플릿, 라벨, PR 템플릿할 일이 이슈로 쪼개져 있는지
Product & Experimentation제품 분석, 실험 인프라실험별 점수와 설정을 기록하는지

Factory 문서는 저장소를 다섯 단계로 나눕니다. 1단계 Functional, 2단계 Documented, 3단계 Standardized, 4단계 Optimized, 5단계 Autonomous입니다. 다음 단계로 올라가려면 이전 단계 기준의 80%를 통과해야 합니다. AGENTS.md와 devcontainer, pre-commit 훅, 브랜치 보호는 2단계의 예시 기준으로 들어가 있습니다. Factory 공지는 공개 저장소 평가 예시로 CockroachDB가 4단계 74%, FastAPI가 3단계 53%, Express가 2단계 28%였다고 소개하면서, 두 프로젝트 모두 성공한 프로젝트지만 에이전트가 기여하기는 CockroachDB 쪽이 훨씬 쉽다고 설명합니다. 대부분의 팀이 먼저 목표로 삼을 지점은 3단계라는 것이 Factory의 안내입니다.

측정은 토큰 사용량이 아니라 결과로 합니다

발표의 마지막 메시지는 측정 지표입니다. Davis Palmie는 코드 줄 수와 생성 토큰 수는 부풀리기 쉬운 지표이고 실제 성과와 연결되지 않는다고 말합니다. 큰 회사의 토큰 사용량 순위표는 낭비를 부추길 뿐이며, 지표가 목표가 되는 순간 좋은 지표가 아니게 된다는 굿하트의 법칙이 실시간으로 벌어지는 사례라고 설명합니다.

얼마나 많은 토큰을 쓰느냐가 아니라, 그 비용으로 얼마나 큰 결과를 얻느냐가 중요합니다.

발표자가 대신 제안한 지표는 다섯 가지입니다. 신호가 들어와 운영 배포까지 걸린 시간, 사람이 개입한 횟수, 복구까지 걸린 시간의 중간값, 코드가 수정 없이 살아남는 기간, PR당 비용입니다. 해커톤 규모로 줄이면 기능 요청이 제출 가능한 상태가 되기까지 걸린 시간, 에이전트 결과를 사람이 고친 횟수, 깨진 빌드를 되살리는 데 걸린 시간 정도를 팀 노트에 남겨 두는 것만으로도 다음 작업에서 에이전트에게 무엇을 맡길지 판단하기 쉬워집니다.

모델은 일에 맞춰 고르고, 한 공급사에 묶이지 않습니다

발표자는 소프트웨어 팩토리의 원칙으로 특정 모델에 종속되지 않을 것, 보안 정책에 맞는 배포 방식을 고를 수 있을 것, 개발 전 과정이 서로 연결될 것을 꼽습니다. 모델 선택에 대해서는 일마다 필요한 최소 성능을 가장 낮은 비용으로 맞추라고 말하며, Factory 내부 사례로 코드 리뷰에서 GPT 5.2가 최신 Opus 모델과 같은 성능을 절반 가격에 냈고, 오픈 소스 대안은 비용을 10~30배까지 줄일 수 있다고 소개합니다. 이 수치는 발표자가 밝힌 자사 관찰이며 별도 공개 평가로 확인한 값은 아닙니다. 그래서 해커톤 팀이라면 이 숫자를 그대로 믿기보다, 같은 작은 과제를 두 모델에 맡겨 테스트 통과 여부와 비용을 함께 적어 보는 쪽이 안전합니다.

오늘 해커톤 저장소에서 할 일: AGENTS.md 한 장

AGENTS.md는 코딩 에이전트에게 맥락과 지시를 주기 위한 공개 형식으로, 공식 사이트는 6만 개가 넘는 오픈 소스 프로젝트가 사용한다고 밝힙니다. 사람을 위한 README와 별도로, 에이전트가 필요로 하는 빌드 단계와 테스트, 코드 규칙을 예측 가능한 위치에 모아 두는 파일입니다. Codex, Cursor, Gemini CLI, Factory 등 여러 도구가 이 파일을 읽습니다. 오늘 할 일은 다음 순서면 충분합니다.

  1. 저장소 루트에 AGENTS.md 파일을 만듭니다.
  2. 설치, 실행, 테스트, 린트 명령을 실제로 한 번씩 돌려 보고 성공한 명령만 그대로 적습니다. 기억에 의존해 적은 명령은 에이전트를 같은 실패로 이끕니다.
  3. 데이터 경로, 제출 파일 이름과 형식, 건드리면 안 되는 폴더를 적습니다. 대회 규정에서 확인한 내용만 옮깁니다.
  4. API 키와 개인 데이터는 커밋하지 않는다는 규칙과 .env 예시 파일 위치를 적습니다.
  5. 작업을 끝내기 전에 테스트를 실행하고 통과를 확인한 뒤에만 커밋하라는 문장을 넣습니다.
  6. 마지막으로 작은 버그 하나를 에이전트에게 맡겨, AGENTS.md를 두기 전과 비교해 사람이 고친 횟수가 줄었는지 팀 노트에 적습니다.

Factory의 Droid를 쓰는 팀이라면 저장소에서 /readiness-report 명령으로 현재 단계와 통과·실패 기준, 다음 단계로 가기 위한 우선 개선 항목 두세 개를 받을 수 있습니다. 공식 문서는 기준마다 Basic, Intermediate, Advanced 난이도가 붙어 있으니 Basic 기준부터 채우라고 안내합니다. 다른 도구를 쓰더라도 위 표를 체크리스트로 삼으면 같은 점검을 할 수 있습니다.

이 발표에서 그대로 가져오지 않아도 되는 것

이 발표는 Factory 제품 소개를 겸하고 있습니다. 배포 방식 선택이나 조직 전체 대시보드 같은 대목은 기업 도입을 전제로 한 내용이라 해커톤 팀에 바로 필요하지는 않습니다. 발표 속 비용 비교 수치도 앞서 밝힌 대로 자사 관찰입니다. 해커톤 팀이 가져갈 것은 두 가지면 충분합니다. 에이전트 결과가 흔들리면 모델보다 저장소 환경을 먼저 의심할 것, 그리고 에이전트에게 맡길 일을 테스트로 확인할 수 있는 작은 일부터 시작할 것입니다. 검색 방식이나 모델을 바꾸기 전에 평가부터 만드는 방법은 어제 DAKER에 정리한 코딩 에이전트 검색 방식 비교 평가 글에서 함께 볼 수 있습니다.

여러분 팀 저장소는 지금 몇 단계쯤이라고 보십니까? AGENTS.md에 꼭 넣어야 한다고 생각하는 한 줄이 있다면 댓글로 나눠 주십시오.

출처