팀에서 AI 코딩 에이전트(예: PR 생성/수정, 리팩터링, 테스트 보강 등)를 실제 개발 프로세스에 붙이려 하고 있습니다. 단순히 프롬프트를 다듬는 방식이 아니라, 레포지토리 자체를 단일 진실의 원천(Single Source of Truth) 으로 두고 에이전트가 “잘 일할 수밖에 없는” 작업 환경(Harness) 을 설계하는 방향을 검토 중입니다.
정리하면 아래 3가지를 하네스의 핵심 축으로 두려 합니다.
컨텍스트 엔지니어링: 지식을 레포 안에 “기계가 읽는 형태”로 정리(예: docs/ + AGENTS.md는 짧은 목차/진입점)
아키텍처 제약: 에이전트의 탐색 공간을 줄이는 검증 가능한 규칙(CI에서 자동 체크 가능한 형태)
엔트로피 관리: 중복/불일치/순환 의존성/죽은 코드 등 품질 저하 요소를 지속적으로 감사/정리
여기서 막히는 지점은, “아키텍처 제약”을 어떤 규칙부터 넣어야 실제 효과(품질/안정성/속도)가 크게 나는지입니다.
규칙 후보는 너무 많고(코딩 스타일, 테스트, 의존성, 모듈 경계, 문서화, 보안 등), 팀 상황에 따라 비용 대비 효용이 크게 달라 보여 우선순위가 어렵습니다.
시도한 것
프롬프트 중심 접근 대신 레포 기반 하네스 설계(문서/제약/피드백/생명주기 관리)로 관점을 전환하려고 조사 중
AGENTS.md는 “백과사전”이 아니라 얇은 목차/가이드로 유지하고, 상세 지식은 docs/로 분리해서 버전 관리하는 방향 검토
CI/CD, 훅, 관측성(로그/메트릭/트레이스)을 연결해 자동 검증 → 실패 피드백 → 자동 수정 루프를 만들면 에이전트 품질이 지속 개선된다는 접근을 참고함
다만, 현재 질문의 핵심은 “첫 단추로 넣을 검증 가능한 규칙이 무엇이냐”라서 구체 규칙 우선순위를 커뮤니티 경험 기반으로 듣고 싶습니다.
기대하는 결과
우리 팀이 하네스에 가장 먼저 넣으면 좋은 “검증 가능한 품질 기준(규칙)” 3~5개 추천
가능하면 아래 조건에 맞는 답변을 기대합니다.
CI에서 자동으로 실패/통과를 판정할 수 있는 형태(예: 린트/타입체크/테스트/의존성 규칙/아키텍처 규칙 등)
단일 진실 원천(SSOT) 기반으로 에이전트가 안전하게 일할 수 있는 환경을 설계하시려는 접근은 매우 최신이자 효과적인 방법으로 보입니다. 조사한 자료들에 따르면, 에이전트의 품질을 높이고 재작업을 줄이기 위해 CI(지속적 통합) 환경에 “첫 단추로” 넣어야 할 검증 가능한 규칙의 우선순위는 다음과 같다고 합니다.
추천하는 “검증 가능한 품질 기준(규칙)” 우선순위 TOP 4
자료에서는 검증 스택을 도입 비용이 낮고 실행이 빠른 것부터, 깊이 있는 논리를 검증하는 순서로 쌓아 올리는 것을 추천한다고 합니다.
1순위: 정적 분석 (Lint 및 Type Check) 강제
이유: 가장 빠르고 도입 비용이 낮으며, 에이전트가 흔히 범하는 문법 및 타입 불일치를 즉각 차단하여 런타임 에러를 원천 방지하기 때문이라고 합니다. 린터가 잡을 수 있는 사소한 스타일 오류를 인간이 리뷰하게 두는 것은 큰 낭비라고 합니다.
CI에서 어떻게 강제했는지: 로컬 환경에서는 husky와 lint-staged를 활용해 커밋 직전(Pre-commit) 변경된 파일에 대해서만 eslint와 tsc --noEmit를 실행하고, CI 파이프라인(예: GitHub Actions)에서는 첫 번째 관문으로 두어 에러가 0개여야만 다음 단계로 넘어가거나 PR이 머지될 수 있도록 설정한다고 합니다.
2순위: 하드코딩 시크릿 차단 (보안 스캔)
이유: 에이전트는 학습 데이터의 패턴을 모방하기 때문에, API 키나 비밀번호를 코드에 평문으로 하드코딩하는 실수를 매우 자주 저지른다고 합니다. 이러한 보안 실수는 발견이 늦어질수록 수습 비용이 기하급수적으로 커지므로 초기에 절대 우회할 수 없는 게이트로 두어야 한다고 합니다.
CI에서 어떻게 강제했는지:gitleaks나 truffleHog 같은 탐지 도구를 CI의 정적 분석과 병렬로 실행하여, 코드에 하드코딩된 시크릿 패턴이 감지되면 즉시 PR을 차단한다고 합니다.
3순위: 계층 간 단방향 의존성 규칙 (아키텍처 제약)
이유: 에이전트는 당장 코드가 작동하게 만들기 위해 계층을 쉽게 파괴하는 경향이 있다고 합니다(예: Service 계층에서 Controller를 참조하거나, UI 컴포넌트가 인프라 코드를 직접 호출). 이를 방치하면 코드베이스가 금세 스파게티 코드로 변해 결국 사람이 대규모로 재작업해야 하는 상황이 발생한다고 합니다.
CI에서 어떻게 강제했는지:dependency-cruiser나 ArchUnit 같은 아키텍처 검증 도구를 CI에 연동한다고 합니다. 만약 에이전트가 의존성 규칙을 위반한 코드를 작성하면 "Service 계층이 Controller 계층을 참조할 수 없습니다"라는 매우 구체적인 에러 메시지를 출력하며 PR을 기계적으로 차단하여 에이전트가 스스로 수정하도록 유도한다고 합니다.
4순위: 신규 코드에 대한 테스트 커버리지 요구 (Test Coverage)
이유: 에이전트가 겉보기엔 작동하는 껍데기 코드만 만들어놓고 "다 했습니다"라고 보고하는 이른바 ‘유령 완료(Phantom Completions)’ 현상을 막기 위해서라고 합니다. 테스트 없이 코드가 올라오는 것을 시스템적으로 차단하여 에이전트가 객관적인 성공 증거를 제출하도록 만듭니다.
CI에서 어떻게 강제했는지: 기존 코드의 전체 커버리지가 아닌, PR에서 "새로 추가된 코드"에 대해서만 특정 수치(예: 80% 또는 90% 이상)의 커버리지를 만족해야 통과하도록 jest나 vitest 설정을 CI 파이프라인에 추가해 강제한다고 합니다.
5순위: 중복 코드 및 엔트로피 감사 (Duplicate/Complex Code Audit)
핵심 가치: 에이전트가 기존 로직을 모르고 비슷한 함수를 또 만드는 ‘코드 증식’ 현상을 억제합니다.
에이전트에게 주는 영향: 에이전트가 코드를 짜기 전, "혹시 비슷한 로직이 이미 있나?"를 검색하게 만드는 동기를 부여합니다.
실행 팁: * jscpd와 같은 도구로 중복도를 체크하거나, 코드 복잡도(Cyclomatic Complexity)가 기준치를 넘으면 경고를 보냅니다.
초기에 하면 역효과 나는 규칙 / 주의사항
하네스 시스템을 처음 구축할 때 흔히 저지르는 실수들도 자료에서 다음과 같이 경고하고 있습니다.
과도하게 복잡한 추상화 요구: 아키텍처 가드레일을 세우겠다고 계층을 7단계로 나누거나 모든 코드를 인터페이스로 감싸버리면, 에이전트가 무엇을 어디서 불러야 할지 몰라 심각한 인지 부하에 빠진다고 합니다. 에이전트에게는 5분 안에 파악할 수 있는 단순한 아키텍처가 가장 좋은 아키텍처라고 합니다.
문서상의 ‘권고 수준’ 규칙: "가급적 지켜주세요"나 "깔끔하게 작성하세요"와 같은 모호한 문구는 에이전트에게 없는 지시와 같다고 합니다. 반드시 “~는 금지된다” 혹은 "~해야 한다"로 명시하고, 이를 CI 도구를 통한 에러 메시지로 "기계적으로 강제"해야 에이전트가 학습하고 수정한다고 합니다.
기존 코드(레거시)에 일괄 규칙 강제 (빅뱅 도입): 기존 프로젝트에 새로운 기계적 제약을 도입할 때 한 번에 모든 위반을 차단하려 하면 CI가 멈춰버려 업무가 마비된다고 합니다. 기존에 위반된 코드는 우선 '경고(Warning)'로 남겨두고, 에이전트가 추가하는 '새로운 위반’만 기계적으로 차단하는 방식으로 점진적 강제를 해야 한다고 합니다.
로컬 단계에서 매번 ‘전체’ 테스트 수트 실행: 에이전트가 코드를 작성한 후 검증 결과를 기다리는 시간이 길어질수록 에이전트의 컨텍스트와 집중력이 심하게 흐트러진다고 합니다. 에이전트가 스스로 에러를 고치는 '자가 수정 루프’의 속도를 높이기 위해서는, 우선 변경된 파일과 관련된 테스트만 실행(관련 검증)하도록 가벼운 스크립트를 도구로 제공해야 한다고 합니다.
실제 조직에 하네스를 도입하실 때, 위와 같이 '비용이 낮고 피드백이 빠른 기계적 검증(Lint/Type/Security)'을 1~2순위로 두시고, 그 후 '아키텍처 제약’과 '테스트 커버리지’를 순차적으로 도입하는 방식이 가장 효과적이라고 하니 참고해 보시기 바랍니다.