핵심 결론
AI-friendly 프로젝트는 모델에게 더 많은 텍스트를 주는 프로젝트가 아니라, 에이전트가 올바른 파일을 찾고 작은 패치를 만들고 검증 증거를 남길 수 있게 경계와 피드백 루프를 설계한 프로젝트다.
1. 구조가 컨텍스트다
폴더, 파일명, 타입명, 테스트명, 문서 위치는 에이전트의 검색 색인이다. domain/application/adapters/contracts/config/tests처럼 책임 경계가 드러나야 localization 비용이 낮아진다.
2. 지침은 짧고 검증은 자동화한다
AGENTS.md류 파일은 보안 통제나 CI의 대체물이 아니다. 전역 지침은 명령, 경계, 증거 형식만 담고 세부 지식은 문서와 테스트로 분리한다.
3. 에이전트 작업은 증거 기반이다
완료 기준은 답변이 아니라 diff, 실행 명령, 테스트 결과, 실패 로그, 남은 위험이다. 테스트와 로그가 다음 iteration의 입력이 되어야 한다.
표준 운영 방법론
| 단계 | 목적 | 프로젝트가 제공해야 할 것 |
|---|---|---|
| Ask / Plan | 목표, 범위, 금지 영역, 검증 명령을 고정한다. | 짧은 작업 계약, 관련 파일 후보, acceptance criteria, 승인 필요 조건 |
| Context construction | 사용자 의도, 현재 코드 상태, 지침, 로그를 역할별로 분리한다. | README, AGENTS류 entry point, docs index, 테스트/실행 명령, 최근 작업 기록 |
| Navigation / localization | 수정 위치를 파일, 클래스, 함수, 테스트 단위로 좁힌다. | 명확한 디렉터리 경계, 심볼 이름, import graph 친화 구조, 검색 가능한 오류 메시지 |
| Edit / patch | 작은 범위의 실제 변경을 만든다. | 원문 파일, 인접 코드, 계약 타입, schema, 가까운 테스트 |
| Execution feedback | 빌드, 타입체크, lint, 테스트, 로그로 수정이 맞는지 확인한다. | 빠른 focused test와 전체 validation의 계층화, deterministic fixture, smoke command |
| Review / evidence | 사람이 검토 가능한 산출물로 마감한다. | 변경 파일, 명령 결과, 실패/재시도 내역, 보안/운영 위험, 후속 작업 |
실무 설계 규칙
저장소 구조
docs/architecture,docs/testing,docs/security,docs/runbooks,docs/decisions를 분리한다.- 소스는 domain, application, adapter, contract, config, interface 경계로 나눈다.
- generated output, lockfile, build artifact는 검색/컨텍스트 예산을 오염시키지 않게 관리한다.
코드 디자인
- 도메인 로직은 side effect를 모르도록 두고, 외부 효과는 adapter와 application orchestration에 모은다.
- 외부 입력은 schema validation을 거쳐 내부 타입으로 변환한다.
- 성공/실패/부분성공 상태는 discriminated union처럼 명시적 계약으로 표현한다.
컨텍스트 검색
- 키워드 검색, semantic search, code graph/repo map을 함께 쓴다.
- 긴 컨텍스트는 RAG를 대체하기보다 recall을 보강하는 계층으로 본다.
- 현재 작업 로그와 실패 테스트는 장기 규칙과 분리해 action history로 남긴다.
Instruction / memory
- 전역 지침은 짧게 유지하고, 상세 정책은 링크 가능한 문서로 둔다.
- 도구별 instruction 파일은 공통 지침의 얇은 어댑터로 관리한다.
- 자연어 지침을 권한, 보안, 배포 승인 로직으로 쓰지 않는다.
멀티에이전트
- 독립 산출물, 병렬 조사, 대안 비교, 별도 리뷰가 필요할 때만 사용한다.
- Orchestrator, Worker, Reviewer, Integrator의 책임을 분리한다.
- Scope, Evidence, Integration, Regression, Approval gate를 둔다.
평가와 벤치마크
- SWE-bench류 점수는 production 신뢰성의 충분조건이 아니다.
- 검색, localization, edit, execution feedback, evidence reporting을 따로 측정한다.
- 테스트 통과 외에 보안, 유지보수성, 리뷰 가능성, 운영 영향을 확인한다.
권장 스타터 체크리스트
- 루트에 짧은
AGENTS.md, 빠른 시작README, 개발 명령 문서를 둔다. - 작업 요청 템플릿은 목표, 범위, 금지, 검증, 승인 필요, 출력 형식을 포함한다.
- 코드 경계는 순수 도메인, use case, 외부 adapter, DTO/schema, config, tests로 나눈다.
- issue와 테스트명은 재현 절차, 기대 동작, 실제 동작, 관련 로그를 드러내게 작성한다.
- 검증 명령은 focused test, compile/typecheck, integration/smoke, full validation 순서로 계층화한다.
- 멀티에이전트 작업은 worker별 산출물 계약과 integrator 책임자가 있을 때만 시작한다.
- 최종 보고에는 변경 요약보다 실행 증거와 남은 위험을 우선 포함한다.
연구가 주는 설계 압력
CodeBERT, GraphCodeBERT, CodeT5, Codex/HumanEval, CodeXGLUE는 모델의 코드 표현과 생성 능력을 설명하지만, 저장소 수준 작업 전체를 보장하지 않는다. 그래서 프로젝트는 모델 능력에 의존하기보다 검색 가능한 구조, 작은 패치, 테스트 피드백, 리뷰 증거를 제공해야 한다.
| 연구/도구 축 | 방법론에 반영할 결론 |
|---|---|
| Foundation papers | 식별자, 주석, docstring, 데이터 흐름, 기능 테스트는 모델 입력의 강한 신호다. |
| Repository benchmarks | 병목은 코드 생성보다 context construction과 localization에 자주 있다. |
| SWE-agent / Agentless / AutoCodeRover / SpecRover | 좋은 ACI, 계층적 localization, AST/code search, specification inference, reviewer confidence가 patch 품질을 높인다. |
| OpenAI Codex loop | 하네스는 thread, tool call, sandbox, approval, diff, test evidence를 일급 상태로 다뤄야 한다. |
| Context tools | repo map, code graph, action history, explicit @file/@folder 컨텍스트는 긴 컨텍스트보다 실무적으로 더 결정적일 수 있다. |
근거 지도
아래 로컬 링크는 생성된 HTML counterpart를 가리킨다. 원문 연구의 외부 URL은 각 세부 페이지에 보존되어 있다.
- AI 보조 / 에이전트형 개발 방법론 작업 루프승인 경계
- AI 친화 폴더 구조와 스타터 템플릿 저장소 구조문서 배치
- AI 친화 코드 디자인 패턴 계층 분리side effect 격리
- Instruction / memory / rules 파일 설계 AGENTSscoped rules
- 멀티에이전트 워크플로 거버넌스 orchestrationgates
- 코드 표현·생성 모델 기초 논문 CodeBERTCodeT5
- 코드 생성·APR 서베이 Big CodeAPR
- Repository-level code editing benchmarks SWE-benchLoCoEval
- 코드베이스 컨텍스트 검색 시스템 CodyAiderCursor
- SWE-agent, Agentless, AutoCodeRover, SpecRover ACIlocalization
- OpenAI 공개 자료 기반 Codex 에이전트 루프 harnesssandbox
운영 원칙 요약
벤치마크, 제품 문서, 에이전트 지침은 모두 보조 근거다. 최종 안전성은 서버 측 권한, CI, 테스트, 로그, 리뷰, 승인 워크플로가 담당해야 한다.