AI Agent Harness — 레포에서 코딩 에이전트를 운용하는 규약 골격

"새로 온 AI 알바생한테 '우리 가게 규칙'을 매번 자동으로 챙겨 읽히는 방법" 이에요. AI 코딩 조수(클로드·코덱스 같은)가 우리 프로젝트에서 일할 때, 규칙을 매번 다시 설명하지 않아도 딱 맞는 순간에 딱 맞는 수칙을 알아서 펼쳐 보게 만들어요.

비유: 가게 벽에 붙은 '운영 수칙' 한 장 📋

새 알바생이 올 때마다 규칙을 말로 다 설명하면 사람마다 다르게 기억하고, 까먹기도 해요. 그래서 가게에는 이렇게 해 둬요.

• 운영 수칙 한 장(AGENTS.md) = 우리 가게 규칙은 딱 한 장에만 적어요. 진짜 원본은 여기 하나뿐.
• 여러 알바생(클로드·코덱스) = 조수가 여럿이어도 각자 다른 수칙을 보면 안 되니까, 모두 그 한 장을 가리키게 해요. 자기 방에 붙은 쪽지는 "저 수칙 보세요" 한 줄뿐이에요.
• 상황별 자동 메모(훅) = "손님이 '환불'이라고 말하면 → 환불 절차 카드를 꺼내 읽어라" 처럼, 특정 단어가 나오면 관련 매뉴얼을 자동으로 손에 쥐여 줘요. 알바생 기억력에 안 맡겨요.
• 수칙 바뀐 이유 기록 = 규칙을 고치면 "왜 고쳤는지"를 같이 적어요. 보통 한 번 사고 난 뒤에 생긴 규칙이라, 다음 사람이 같은 실수를 안 하게요.

핵심은 하나예요: 규칙을 여기저기 베껴 두지 않고 한 곳에만 두기. 베껴 두면 반드시 서로 어긋나요.

규칙이 한 곳으로 모이는 그림

딱 맞는 순간에 매뉴얼 꺼내 주기

알바생이 뭔가 하려고 할 때, 말 속 단어를 보고 필요한 매뉴얼을 자동으로 펼쳐 줘요.

• 꼭 지켜야 하는 규칙이면 "이거 먼저 읽고 시작해!" 하고 강제로 쥐여 줘요.
• 참고만 하면 되는 것이면 "이런 것도 있어" 하고 살짝 알려만 줘요.
• 실수하면 큰일 나는 무거운 작업은 아무 때나 못 하게 잠가 두고, 사람이 콕 집어 시킬 때만 하게 해요.

트레이드오프도 쉽게: 규칙을 자동으로 꽉 강제하면 실수는 줄지만 자유로운 탐색이 답답할 수 있고, 느슨하게 두면 편하지만 사람마다 편차가 생겨요. 중요한 규칙일수록 꽉, 실험 위주면 느슨하게 골라요.

핵심만 다시

1. 규칙은 한 장(원본) 에만 적고, 모든 AI 조수가 그 한 장을 가리키게 해요.
2. 특정 단어가 나오면 관련 매뉴얼을 자동으로 쥐여 줘요 — 조수 기억력에 안 맡겨요.
3. 꼭 지킬 건 강제, 참고할 건 추천 으로 세기를 조절해요.
4. 규칙을 고치면 왜 고쳤는지도 같이 남겨서 다음 사람이 같은 실수를 안 하게 해요.

더 자세한 진짜 코드·설계는 옆의 개요 / Variants / Apply Recipe 탭에서 볼 수 있어요.