AI 코딩 에이전트는 저장소(repository)가 실제로 준비되기 훨씬 이전부터 유용합니다.

위험한 순간은 에이전트가 코드를 읽을 때가 아닙니다. 파일 편집, 상태를 변경하는 명령어 실행, 또는 병합하기에 충분히 그럴듯해 보이는 변경 사항을 준비할 수 있을 때입니다.

쓰기 접근 권한을 부여하기 전에 이 5분 점검(preflight)을 수행하세요.

1. 깨끗한 체크아웃으로 작동 상태에 도달할 수 있는가?

정확한 런타임 버전, 종속성 설치 명령어, 그리고 예상되는 성공 신호를 문서로 작성하세요.

만약 설정이 부족한 지식(tribal knowledge)—채팅에서 복사된 환경 변수, 아무도 문서화하지 않은 전역 패키지, 또는 한 팀원만이 아는 서비스—에 의존한다면, 에이전트는 해당 환경을 신뢰성 있게 재현할 수 없습니다.

통과 조건: 새로운 기여자가 추측 없이 저장소의 지침을 따를 수 있어야 합니다.

2. 빠른 검증 명령어가 있는가?

에이전트는 변경 사항이 아직 작을 때 피드백이 필요합니다. 40분짜리 CI 파이프라인은 유용하지만, 실질적인 내부 루프(inner loop)는 아닙니다.

몇 분 안에 일반적인 실수를 잡아낼 수 있는 집중된 명령어 하나를 문서화하세요: 목표 테스트, 타입 체크, lint 작업, 또는 작은 빌드. 전체 검증 스위트(suite)는 별도의 최종 점검으로 유지합니다.

통과 조건: 저장소에 빠르고 로컬에서 실행 가능한 확인 기능과 문서화된 전체 검증 경로가 모두 있어야 합니다.

3. 변이 경계(mutation boundaries)가 명시적인가?

파일을 읽는 것이 인프라를 변경하는 것과는 다릅니다. 종속성을 설치하는 것이 배포하는 것과는 다릅니다. 생성된 코드를 업데이트하는 것이 그 소스를 편집하는 것과는 다릅니다.

지침은 다음 사항들을 분리해야 합니다:

• 안전한 검사(safe inspection);
• 일반 파일 편집(normal file edits);
• 종속성 또는 생성된 아티팩트를 변이시키는 명령어(commands that mutate dependencies or generated artifacts);
• 파괴적인 작업(destructive operations);
• 프로덕션, 청구, 및 인프라 변경 사항.

통과 조건: 승인이 필요한 동작은 암시되는 것이 아니라 명명되어야 합니다.

4. 비밀 정보와 신뢰할 수 없는 콘텐츠가 최우선 위험으로 처리되는가?

자격 증명(credentials)은 커밋된 소스 파일뿐만 아니라 로그, 스크린샷, 테스트용 더미 데이터(fixtures), 및 진단 기록을 통해 유출됩니다.

동시에, 이슈(issues), 풀 리퀘스트(pull-request) 설명, 웹 페이지, 로그, 그리고 생성된 파일들은 지시 사항(instructions)처럼 보이는 텍스트를 포함할 수 있습니다. 에이전트는 신뢰할 수 있는 저장소 가이드(repository guidance)에서 달리 명시하지 않는 한, 이러한 소스들을 데이터로 취급해야 합니다.

통과 조건 (Pass condition): 저장소가 민감한 출력물을 식별하고 지시 권한 경계(instruction-authority boundary)를 정의해야 합니다.

5. 인수인계(handoff) 과정에서 발생한 일을 증명할 수 있는가?

"완료됨"이라는 말은 유용한 결과가 아닙니다.

A 강력한 인수인계는 변경된 파일, 실행된 명령(commands), 관찰된 결과, 건너뛴 체크 사항, 그리고 남아있는 불확실성을 명시합니다. 이는 검토자에게 결론을 재현할 수 있는 충분한 증거를 제공합니다.

통과 조건 (Pass condition): 작업 또는 풀 리퀘스트(pull-request) 템플릿이 검증 증거를 요구해야 합니다.

답변을 점수로 변환하기

각 영역에 대해 0점에서 2점까지 점수를 매기세요:

• 0: 누락됨;
• 1: 문서화되었으나 불완전하거나 검증되지 않음;
• 2: 문서화되었으며 현재의 증거로 뒷받침됨.

낮은 점수가 "에이전트를 절대 사용하지 마라"는 뜻은 아닙니다. 이는 읽기 전용(read-only) 모드나 엄격하게 감독되는 모드로 시작하여 가장 중요한 격차(gaps)를 먼저 해결하라는 의미입니다.

저는 이 내용을 20점 만점의 점수로 확장한 무료 브라우저 전용 버전을 만들었습니다. 계정이 필요 없으며 아무것도 업로드하지 않습니다:

무료 Agent-Ready Repo Audit 실행하기

소스 코드는 GitHub에도 공개되어 있습니다.

모든 정책을 처음부터 직접 작성하는 대신 바로 구현 가능한 파일이 필요하다면, Agent-Ready Repo Kit에 저장소 지침, 보안 가드레일(security guardrails), 워크플로(workflows), 인수인계 템플릿, 스코어카드(scorecard), 그리고 의존성이 없는 검증기(zero-dependency validator)가 포함되어 있습니다.

공개 사항: 감사(audit) 및 저장소(repository)는 무료입니다. 마지막 링크는 제가 판매하는 제품으로 연결됩니다. 이 글은 AI의 도움을 받아 초안을 작성하였으며, 발행 전 검토를 거쳤습니다.