코딩 에이전트 운용 사내 가이드

막히는 원인은 도구 성능이 아니라 맥락이 흩어지는 데 있었습니다. 세 가지 증상을 문제로 잡고, 각각에 대응하는 규칙을 하나씩 붙였습니다.

매번 구술

프로젝트 설명을 세션마다 다시 말해야 합니다. 상시 지침 파일로 대응합니다.

주제 혼합

한 대화에 여러 주제가 섞입니다. 대화 하나에 주제 하나만 둡니다.

합의 소실

앞서 합의한 것이 사라집니다. 기억 파일과 작업 목록에 적어 둡니다.

대화는 쓰고 버리는 작업 단위로 두고, 남길 것은 파일에 적는다는 전제 위에 나머지 규칙이 놓입니다.

규칙은 석 달치 사용 기록에서 나왔습니다. 기록이 있는 98일의 수치를 먼저 보이되 자랑이 아니라 깨진 지점의 수습 기록으로 규정하고, 거기서 나온 규칙만 담았습니다.

2026년 6월 6일부터 9월 11일까지의 발표자료 기준 수치입니다. 블로그 글의 집계(762억 토큰)는 집계 시점이 달라 값이 다릅니다.

대화는 열기에서 닫기까지 한 주기로 돌고, 프로젝트 폴더는 지침·기억·작업 목록 같은 파일로 나누어 구성합니다. 대화를 열 때 성격에 맞는 모델을 먼저 고르고 중간에 바꾸지 않습니다.

작업은 로컬 폴더, 제출 문서의 정본은 클라우드 과제 폴더, 팀 공유 자료는 사내 공유 자료실에 두고 서로의 위치를 적어 둡니다. 클라우드 동기 폴더에는 빌드 캐시를 두지 않습니다.

지시보다 먼저 지침·기억·작업 목록 세 파일을 읽히고, 현황을 보고받은 뒤 착수합니다. 엉뚱한 파일을 고치는 사고를 막기 위한 순서입니다.

보고 순서

지금 하는 일, 남은 일, 사람이 결정할 일의 순서로 받습니다.

다른 일이 떠오를 때

작업 중 다른 일이 떠오르면 지금 대화의 결론을 바꾸는지 따져 봅니다. 급하면 새 대화를 열고, 아니면 작업 목록에 한 줄만 남기고 원래 주제로 돌아옵니다.

지시문은 명사만 던지지 않고 동사로 끝맺습니다. 동작과 범위, 멈출 지점을 함께 적고, 결과의 형태와 근거 요구까지 덧붙입니다.

동작·범위·멈출 지점

'확인' 한 단어 대신 '이 값이 설정 파일과 맞는지 확인하고, 다르면 어디가 다른지만 알려 주고 고치지는 마'처럼 동작과 범위, 멈출 지점을 함께 적습니다.

결과의 형태

표, 경로와 줄 번호, 세 줄 이내처럼 받을 모양을 정해 줍니다.

근거 요구

판단마다 근거를 함께 내게 합니다.

발표자료에는 이런 지시문 예시가 상황별로 17종 실렸습니다.

닫기 전에 세 가지를 남깁니다. 작업 목록 갱신, 원인과 판단 근거를 담은 기억 한 건, 하다 만 작업의 시작점 한 줄입니다.

정본과 근거 자료를 옮기고 남은 파일은 승인을 받은 뒤에 지웁니다.

기억 파일은 사실 하나에 파일 하나로 두고, 머리말 세 줄과 판단 이유를 적습니다. 이유가 없는 규칙은 다음 사람이 되돌리기 때문입니다.

남기는 것

겪은 함정과 원인, 정해진 규칙과 배경, 외부 자원의 위치입니다.

남기지 않는 것

코드를 보면 알 수 있는 사실입니다.

기록 기준

찾는 데 30분 걸린 것은 기록하고, 30초 안에 다시 찾을 수 있는 것은 기록하지 않습니다.

먼저 낡는 것

경로·포트·버전·담당이 가장 먼저 낡으므로, 인용하기 전에 파일과 함수가 지금도 있는지 확인합니다.

병합과 삭제

같은 주제의 기억은 병합하고 낡은 서술은 현재 사실로 교체합니다. 계획을 확인한 뒤 승인분만 실행합니다.

작업 목록은 항목 하나를 한 줄, 한 가지 일로 적습니다. 항목의 문구가 식별자라서, 상태만 바꾸려다 문구까지 고치면 새 항목으로 인식됩니다.

분리

상태 변경과 문구 수정을 나누고, 섹션을 옮길 때도 줄만 옮깁니다.

현황판

프로젝트마다 이 파일이 모이면 전사 현황판의 데이터 원본이 되어, 어디까지 갔는지 묻지 않고 볼 수 있습니다.

아침 점검

아침에는 남은 건수가 늘어나는 과제부터 확인합니다.

합의는 대부분 메일에서 정해지므로 수신분과 발송 초안을 프로젝트 폴더에 기록으로 남기고, 회의는 녹음부터 작업 목록까지 이어서 정리합니다. 같은 일이 반복되는 산출물은 스킬로 굳혔습니다.

이름 규칙

과제 폴더는 연월과 과제명으로 짓고, 파일은 날짜 8자리와 이름을 공백으로 이어 붙입니다. 구버전은 지우지 않고 이전 버전 폴더로 옮깁니다.

스킬화 시점

같은 일을 두 번째 하는 시점에, 방금 쓴 명령과 판단을 근거로 만듭니다. 지침은 항상 지킬 규칙이고 스킬은 필요할 때 부르는 절차입니다.

공유 전 점검

팀에 공유하기 전에 다른 사람의 환경에서 한 번 실행하고, 경로·자격 증명 같은 개인 설정을 뺍니다.

새 과제는 처음 10분에 폴더와 지침 초안을 만들어 두는 것으로 시작합니다. 겪은 실패는 아홉 가지 패턴으로 묶어, 앞서 본 규칙과 하나씩 짝지었습니다.

발표는 한 장 요약과 프롬프트 목록 배포, 새 과제 초기 설정 지원을 다음 단계로 제시하며 끝납니다.