Claude Code와 Codex로 개발했다. 처음엔 AGENTS.md에 넘으면 안 되는 규칙만 적어두고, 에이전트는 pytest와 ruff만 통과하면 다 됐다고 보고했다. 10월에 다시 들여다보니 테스트가 실제 키와 외부망에 닿을 수 있었고, 완료 기준은 로컬과 CI, 문서마다 달랐다. 그래서 검증 방법과 검토 항목까지 저장소에 넣어 코드와 같이 관리하기 시작했다.

두 에이전트는 같은 규칙과 스킬을 읽는다. Claude Code는 CLAUDE.md의 @AGENTS.md로 규칙을 읽고, Codex는 .agents/skills 링크로 같은 스킬을 읽는다.

겪은 일과 넣은 규칙

겪은 일 그래서 넣은 규칙
모의 테스트가 로컬 .env의 실제 서비스 키를 읽을 수 있었다 테스트에서는 .env를 읽지 않고 *_key 환경변수를 지운다
테스트가 외부로 나가는 걸 막는 장치가 없었다 localhost 밖 연결 차단. Windows 이벤트 루프는 socket.connect를 거치지 않아서 이름 조회부터 막는다
7월에 올린 세 번 모두 CI가 배포 안전 검사에서 실패했다. Windows에서는 드러나지 않는 오류였고, 로컬 완료 기준에는 이 검사가 없었다 검사 스크립트를 고치고, 로컬과 CI가 같은 게이트를 돌린다
테스트 통과 수를 문서에 손으로 옮겨 적었다 실행 기록 파일의 값으로만 보고하고, 문서에는 숫자를 고정하지 않는다

CI 실패는 비밀값 때문이 아니라 검사 스크립트가 죽어서였다. 리눅스 venv의 python은 저장소 밖을 가리키는 링크라서, 모든 파일 경로를 풀어 저장소 기준으로 바꾸던 검사가 여기서 예외를 냈다. Windows venv에는 이런 링크가 없어서 로컬에서는 드러나지 않았다. 지금은 제외 폴더를 아예 탐색하지 않는다.

검증 게이트

scripts/verify.py가 ruff → 배포 안전 검사 → uv lock --check → pytest를 순서대로 돌리고 첫 실패에서 멈춘다. 결과는 .harness/runs/<id>/result.json에 남는다. 빠르게 반복할 때는 pytest를 뺀 --fast를 쓴다.

검사 도중 저장소 파일이 바뀌면 workspace_mutated로 실패 처리한다. 어떤 작업 트리를 검증했는지 알 수 없는 기록이 되니까.

보고는 마지막 변경 뒤에 나온 기록으로만 한다. 건너뛴 실행이나 도중에 파일이 바뀐 실행을 통과로 적지 않는다. 다른 세션의 변경 때문에 게이트가 실패하면 실행 id와 원인, 대상 테스트 결과를 부분 확인으로 보고한다.

저장소에 올리면 GitHub Actions가 같은 게이트를 돌린 뒤 Docker 이미지 빌드까지 확인한다.

검토 스킬

판단 엔진, 사용자 답변, 근거 상태, MCP 도구와 공개 schema를 바꾼 변경은 마치기 전에 accessibility-review 스킬로 본다. 검토하는 동안에는 고치지 않고 발견부터 보고한다.

항목 보는 것
단정 금지 근거가 끝까지 확인되지 않았는데 "안전", "이용 가능"으로 읽히는 문구. 금지어 목록을 비켜 가는 비슷한 표현까지
상태 구분 확인과 미확인, 지원 범위 밖, 외부 API 실패가 한 상태로 합쳐지지 않았는가
결정론 위험도와 판정이 엔진에서만 정해지는가. LLM 호출, 난수, 고정할 수 없는 현재 시각 의존이 없는가
답변 순서 첫 몇 줄에 결론과 다음 행동이 있는가
키 노출 로그·응답·fixture·검증 기록에 서비스 키나 키가 붙은 URL이 없는가
공개 계약 도구 8개의 이름·인자와 출력 schema가 하위 호환되는가
테스트 새 동작마다 대표 질문 fixture와 회귀 테스트가 있는가

결과에는 판정과 검토 방식을 같이 적는다. 변경한 세션이 직접 본 건 자체 점검, 변경하지 않은 서브에이전트나 다른 도구가 본 건 독립 검토다. 자체 점검을 독립 검토로 적지 않는다.

권한과 작업 규칙