한 개발자는 테스트 통과를 완료라고 부르고, 다른 개발자는 운영 화면 확인까지 끝나야 완료라고 부릅니다. 같은 도구를 써도 이 기준이 다르면 인계 때마다 빈칸이 생깁니다. 팀에는 프롬프트 모음보다 누가 무엇을 승인하고 어떤 증거를 남기는지 정한 공통 규칙이 필요합니다.
핵심 팀 운영에 필요한 규칙을 착수·구현·종료 세 단계, 아홉 항목으로 정리했습니다. 개인 세션 관리가 아니라 저장소·권한·검증·배포의 공통 계약에 집중합니다.
팀 작업도 복사 가능한 첫 프롬프트에서 시작합니다
다음은 예시이며 경로와 승인자는 팀 저장소에 맞춥니다.
claude --permission-mode plan
이슈의 결제 재시도 변경을 계획하세요. 아직 수정하지 마세요.
읽기: CLAUDE.md, AGENTS.md, 이슈, server/payment/**, 테스트 규칙
허용: Read, Grep, 기존 테스트 조회
금지: 공용 라우터, 운영 데이터, commit·push·deploy
반환: 소유 파일 / 공유 파일 충돌 / 검증 명령 / 승인 지점 / 완료 보고 형식
중단: 승인자나 공용 파일 담당자가 정해지지 않았을 때담당자가 계획을 승인한 뒤 구현과 운영을 분리합니다
계획이 승인되면 소유 파일 목록을 그대로 구현 경계로 씁니다. 결과 보고서에는 바뀐 파일, 실행한 검증과 아직 확인하지 못한 항목을 나눠 적고 상태 변경과 배포는 제외합니다. 다른 팀의 계약 변경은 코드가 아니라 별도 제안으로 남깁니다.
리뷰어는 팀 검증 명령과 변경 차이를 대조합니다. 완료 증거가 없거나 구현과 운영 승인이 한 자동 단계에 섞이면 작업을 닫지 않습니다. 인계 메모에는 담당자, 승인 범위와 남은 배포 절차가 있어야 합니다.
예시 장애는 완료의 뜻에서 시작됩니다
팀 규칙이 필요한 장면을 가정해 봅시다. 에이전트가 결제 오류를 수정하고 단위 테스트를 통과시킨 뒤 담당자는 완료로 표시했지만, 환경변수가 빠진 운영 배포는 실패합니다. 배포 담당자는 어떤 커밋과 변수 이름을 확인해야 하는지 알지 못합니다.
이 예시에서 팀은 긴 프롬프트 모음 대신 반복 사고를 막는 규칙만 남기기로 합니다.
착수 규칙 세 개가 다른 사람의 작업을 보호합니다
규칙 1은 작업 전 원격 최신 상태와 사용자 변경을 확인하는 것입니다. 규칙 2는 수정할 경로와 공용 파일 담당자를 정하는 것입니다. 규칙 3은 운영 데이터, 비밀, 배포처럼 에이전트가 건드리지 않을 영역을 적는 것입니다.
이 세 규칙은 에이전트의 능력을 제한하려는 것이 아니라 동료의 변경과 운영 자격을 보호합니다.
구현 규칙 세 개는 검토 가능한 변경을 만듭니다
규칙 4는 한 작업에 하나의 관찰 가능한 결과, 규칙 5는 작은 변경 차이, 규칙 6은 코드와 함께 실행할 검증 명령입니다.
목표: 결제 재시도에서 같은 결과 반환
소유: server/payment/**, tests/payment/**
공유 파일: routes.ts는 통합 담당만 수정
금지: 운영 DB, 비밀 조회, 배포
완료 증거: 재시도 회귀 + 결제 전체 테스트
승인자: 서버 담당
배포 담당: 릴리즈 담당종료 규칙 세 개가 금요일의 빈칸을 없앱니다
규칙 7은 실행한 테스트와 하지 못한 검증을 분리하는 것입니다. 규칙 8은 배포가 범위라면 실제 URL, 로그, 롤백 지점을 확인하는 것입니다. 규칙 9는 결정과 운영 변경을 팀의 기준 문서에 짧게 남기는 것입니다.
“테스트 통과”는 저장소 검증의 완료일 수 있지만 운영 완료와 같지 않습니다. 상태 변경과 배포는 정해진 사람이 승인합니다.
규칙은 사고를 줄였을 때만 남깁니다
도입 뒤 정기 검토에서는 배포 실패, 공유 파일 충돌, 미검증 누락이 줄었는지 봅니다. 쓰이지 않는 체크 항목은 지우고 실제 사고에 기여한 규칙만 고칩니다. 규칙 수를 늘리는 것이 성숙함은 아닙니다.
보호 브랜치를 우회하거나 검증 결과가 없거나 승인자가 불명확하면 작업을 멈춥니다. 자동화는 빈도가 높고 성공·실패가 결정적이며 쉽게 되돌릴 수 있는 규칙부터 적용합니다.