문제 상황
팀에서 AI 코딩 에이전트(예: PR 생성/수정, 리팩터링, 테스트 보강 등)를 실제 개발 프로세스에 붙이려 하고 있습니다. 단순히 프롬프트를 다듬는 방식이 아니라, 레포지토리 자체를 단일 진실의 원천(Single Source of Truth) 으로 두고 에이전트가 “잘 일할 수밖에 없는” 작업 환경(Harness) 을 설계하는 방향을 검토 중입니다.
정리하면 아래 3가지를 하네스의 핵심 축으로 두려 합니다.
- 컨텍스트 엔지니어링: 지식을 레포 안에 “기계가 읽는 형태”로 정리(예: docs/ + AGENTS.md는 짧은 목차/진입점)
- 아키텍처 제약: 에이전트의 탐색 공간을 줄이는 검증 가능한 규칙(CI에서 자동 체크 가능한 형태)
- 엔트로피 관리: 중복/불일치/순환 의존성/죽은 코드 등 품질 저하 요소를 지속적으로 감사/정리
여기서 막히는 지점은, “아키텍처 제약”을 어떤 규칙부터 넣어야 실제 효과(품질/안정성/속도)가 크게 나는지입니다.
규칙 후보는 너무 많고(코딩 스타일, 테스트, 의존성, 모듈 경계, 문서화, 보안 등), 팀 상황에 따라 비용 대비 효용이 크게 달라 보여 우선순위가 어렵습니다.
시도한 것
- 프롬프트 중심 접근 대신 레포 기반 하네스 설계(문서/제약/피드백/생명주기 관리)로 관점을 전환하려고 조사 중
AGENTS.md는 “백과사전”이 아니라 얇은 목차/가이드로 유지하고, 상세 지식은docs/로 분리해서 버전 관리하는 방향 검토- CI/CD, 훅, 관측성(로그/메트릭/트레이스)을 연결해 자동 검증 → 실패 피드백 → 자동 수정 루프를 만들면 에이전트 품질이 지속 개선된다는 접근을 참고함
- 다만, 현재 질문의 핵심은 “첫 단추로 넣을 검증 가능한 규칙이 무엇이냐”라서 구체 규칙 우선순위를 커뮤니티 경험 기반으로 듣고 싶습니다.
기대하는 결과
- 우리 팀이 하네스에 가장 먼저 넣으면 좋은 “검증 가능한 품질 기준(규칙)” 3~5개 추천
- 가능하면 아래 조건에 맞는 답변을 기대합니다.
- CI에서 자동으로 실패/통과를 판정할 수 있는 형태(예: 린트/타입체크/테스트/의존성 규칙/아키텍처 규칙 등)
- 에이전트가 PR을 만들 때 재작업을 크게 줄여주는 규칙
- 도입 비용 대비 효과가 큰 순서(우선순위)와 간단한 근거
예시로는 이런 스타일의 답변을 원합니다:
- “1순위: (규칙) — (이유) — (CI에서 어떻게 강제했는지)”
- “초기에 하면 역효과 나는 규칙/주의사항”도 있으면 도움 될 것 같습니다.