작업 워크플로우

원칙 1~5가 "환경 정돈"이었다면, 원칙 6~11은 그 환경 안에서 한 작업을 어떻게 시작·진행·마무리하느냐예요. 시작 단계의 판단이 결과 품질의 절반을 결정해요.

새 작업이 들어왔을 때 — 결정 흐름

원칙 6~11의 큰 그림을 한눈에 보면, 새 작업을 받았을 때 어떤 길로 갈지 흐름도가 보여요.

흐름의 핵심: 명확하지 않으면 Plan Mode(원칙 8), 기계적이면 스크립트(원칙 9), 범위가 넓으면 쪼개기(원칙 11). 그리고 어느 분기든 끝에는 체크리스트(원칙 6) + CONTINUE.md(원칙 7) 가 따라와요.

원칙 6: 대규모 작업은 체크리스트로 격파하라

연관된 작업이라도 한 세션에서 전부 처리하려 하면 컨텍스트가 부족해요. 대규모 작업을 시작할 때는 먼저 체크리스트를 만들고, 항목 하나씩 격파해 보세요.

## 리팩터링 체크리스트
- [x] auth 모듈 분리
- [ ] API 레이어 분리
- [ ] 테스트 커버리지 확인
- [ ] 문서 업데이트

워크플로우:

1. 세션 시작 시 작업 목록을 checklist.md에 정리
2. 항목 하나를 완료하면 체크 표시 후 커밋 (커밋이란?)
3. 필요하면 새 세션을 열고 다음 항목 진행

한 세션에서 모두 처리하면 컨텍스트가 무거워지고, Compaction이 앞에서 한 작업 내용을 날려요. 세션마다 항목 하나에 집중하면 각 세션이 가볍고 깨끗하게 유지돼요.

체크리스트 파일은 시스템 프롬프트 파일(CLAUDE.md/AGENTS.md)에 트리거로 연결해두면 다음 세션에서 자동으로 로드돼요.

## 트리거 참조
- 진행 중인 작업이 있으면: 반드시 `checklist.md`를 먼저 읽어라

원칙 7: 세션 핸드오프 — CONTINUE.md 패턴

세션을 닫을 때 "문서 정리해줘"라고 하면 에이전트가 다음 세션용 인수인계 문서를 작성해요. 다음 세션에서 @CONTINUE.md 한 마디면 즉시 상황 브리핑과 다음 할 일을 받을 수 있어요.

비유로 풀면 — 교대 근무 일지예요. 야간조에서 주간조로 넘어갈 때, 어디까지 했고 무엇이 미해결이고 누구에게 무슨 알림이 와야 하는지를 한 장에 적어두면, 새 사람이 즉시 일을 이어갈 수 있어요. CONTINUE.md가 정확히 이 역할이에요.

그런데 세션을 새로 열지, 아니면 지금 세션을 이어갈지 판단이 서지 않을 때가 있어요. 이것도 에이전트에게 물어보면 돼요.

"지금 세션 정리하고 새로 시작하는 게 나을까, 아니면 여기서 계속하는 게 나을까?"

남은 컨텍스트 여유, 다음 작업과의 연관성, 현재 세션에서 파악한 정보의 재사용 가치를 에이전트가 종합해서 판단하고 권장해줘요.

시스템 프롬프트 파일 vs CONTINUE.md 역할 분리:

트리거와의 차이:

• @CONTINUE.md 직접 태그 → "이어하자"는 의도적 재개. 에이전트가 즉시 브리핑하고 다음 할 일을 제안해요.
• 시스템 프롬프트 파일 트리거 → 태그를 까먹었을 때의 안전망. 두 가지를 함께 써도 충돌하지 않아요.

무엇을 어디에 쓸 것인가:

• CONTINUE.md: 지금 어디까지 했고, 미해결 이슈가 뭔지, 다음 세션에서 무엇부터 할지
• 시스템 프롬프트 파일: 반복되는 실수에서 얻은 교훈, 아키텍처 결정, 스타일 규칙 — 세션이 바뀌어도 유지해야 할 것

세션 단위 작업 상태를 시스템 프롬프트 파일에 쌓지 마세요. 파일이 두꺼워지고, Compaction 후에도 계속 정적 레이어를 차지해요.

설정 방법 — 전역 시스템 프롬프트 파일에 트리거 등록:

"문서 정리해줘" 한 마디로 CONTINUE.md가 자동 생성되는 건 전역 시스템 프롬프트 파일에 자연어 트리거를 등록해뒀기 때문이에요. Claude Code라면 ~/.claude/CLAUDE.md, Codex라면 글로벌 AGENTS.md에 아래처럼 작성해요.

## 세션 정리 트리거

사용자가 "문서 정리해", "세션 정리해", "다음 세션 지침 만들어" 등의 뉘앙스로 요청하면:
1. 프로젝트 루트의 시스템 프롬프트 파일에 이번 변경으로 생긴 영속적 정보를 반영한다
2. 프로젝트 루트의 `CONTINUE.md`에 현재 작업 상태·미해결 이슈·다음 단계를 기록한다
3. 작성 후 "CONTINUE.md 준비 완료, 새 세션에서 `@CONTINUE.md`로 이어가면 돼!" 안내

전역 지침에 등록하면 모든 프로젝트 세션에 적용돼요. 특정 프로젝트에만 다르게 동작하게 하려면 해당 프로젝트의 시스템 프롬프트 파일에 덮어쓰면 돼요.

이것이 원칙 5의 트리거 패턴을 메타적으로 적용한 사례예요 — 에이전트 자체의 동작을 시스템 프롬프트 자연어 지침으로 확장하는 방식이에요.

원칙 8: 계획 모드로 먼저 상의하라

작업을 시작할 때 요구사항이 완전히 명확한 경우는 드물어요. 일부 조건을 빠뜨리거나, 목표 자체가 모호하거나, 무엇이 필요한지 시작해봐야 알게 되는 경우가 많아요. 이 상태에서 바로 실행에 들어가면 엉뚱한 방향으로 구현이 진행되고, 수정 비용이 커져요.

Plan Mode는 에이전트가 파일을 읽거나 코드를 수정하지 않고, 구현 계획만 텍스트로 제안하는 모드예요. 실행 전에 방향을 조율하는 대화 공간이에요.

진입 방법(Claude Code 기준):

Shift+Tab   # 입력창에서 토글
/plan       # 슬래시 커맨드

Codex CLI 등 다른 에이전트도 비슷한 계획 모드·승인 단계를 제공해요(상세는 Codex 사용 가이드).

계획 모드에서 에이전트는 "어떤 파일을 어떻게 수정할지, 어떤 순서로 진행할지"를 먼저 제안해요. 이 단계에서

• 빠뜨린 조건을 발견할 수 있어요
• "이 부분은 이렇게 바꿔줘"로 방향을 수정할 수 있어요
• 에이전트가 잘못 이해한 부분을 실행 전에 잡을 수 있어요.

계획이 충분히 구체화되면 승인하고 실행해요. 계획 없이 바로 실행했을 때보다 결과물이 요구사항에 맞을 확률이 높고, 재작업이 줄어요.

복잡한 작업일수록, 요구사항이 모호할수록 계획 모드로 시작하세요. 충분히 상의하고 나서 실행하는 게 처음부터 다시 짜는 것보다 빨라요. 목수의 격언 그대로 — 두 번 재고 한 번 자른다.

계획 모드가 필요한지 판단이 서지 않으면, 에이전트에게 직접 물어보세요.

"이 작업, 바로 시작해도 될까 아니면 계획 모드로 먼저 정리하는 게 나을까?"

작업의 복잡도와 모호성을 에이전트 스스로 판단하고 권장해줘요.

원칙 9: 반복·기계적 작업은 스크립트를 먼저 작성하게 하라

같은 패턴의 작업을 LLM이 직접 반복 처리하면 두 가지 문제가 생겨요. 파일 하나를 읽을 때마다 내용 전체가 컨텍스트에 쌓이고, 중간에 오류가 나면 어디서 틀렸는지 추적하기 어려워요.

워크플로우를 바꿔보세요:

1. "이 작업을 셸 스크립트(또는 파이썬 스크립트)로 짜줘"
2. 스크립트가 의도한 대로 동작하는지 확인
3. 실행 → 결과만 확인

LLM이 직접 100개 파일을 열어 수정하면 컨텍스트에 100번 쌓여요. 스크립트로 위임하면 최종 실행 결과 한 줄만 들어와요. 스크립트는 파일로 남으니 재사용과 수정도 쉬워요.

비용 관점에서 한 줄 비교:

스크립트 방식이 유리한 작업:

• 파일 이름·디렉토리 일괄 정리
• CSV / JSON 데이터 일괄 변환·정제
• 코드베이스 전체 패턴 치환 (find & replace)
• 로그 분석, 반복 빌드·테스트 자동화

LLM이 직접 처리하는 게 나은 경우: 파일마다 내용을 이해하고 판단해야 하거나, 맥락에 따라 처리 방식이 달라지는 작업은 스크립트화하기 어려워요. 이런 작업은 서브에이전트 위임(섹션 4)을 고려해 보세요.

코딩 에이전트는 어느 정도 스스로 판단하기도 하지만, 명시적으로 "스크립트 먼저 짜줘"라고 요청하면 더 일관되게 동작해요.

원칙 10: 가짜 테스트 입력 생성도 맡겨라

함수를 모듈 단위로 작성하면 테스트가 필요해요. 그런데 "그럴듯한 가짜 입력"을 손으로 만드는 건 생각보다 시간이 걸려요. 실제 데이터가 없거나 민감 데이터라 직접 쓸 수 없는 경우는 더욱 그렇죠.

에이전트는 이 작업을 즉시 해줘요.

"이 함수에 대한 테스트 스크립트 짜줘. 정상 케이스 3개 + 엣지 케이스 2개."
"이 JSON 스키마에 맞는 샘플 데이터 100개 생성하는 스크립트 만들어줘."
"이 클래스 테스트할 가짜 입력 만들어줘."

테스트 데이터뿐 아니라 테스트 스크립트 자체도 뚝딱 만들어줘요. 코드 구조를 읽고 "어떤 입력이 의미 있는지"를 스스로 판단하기 때문에 가능한 일이에요.

효과적인 모듈 테스트 워크플로우:

1. 함수 구현 완료
2. "이 함수 테스트 스크립트 짜줘, 엣지 케이스 포함" 요청
3. 스크립트 검토·실행
4. 실패 케이스 발견 → 구현 수정

모듈화와 코딩 에이전트를 조합하면 테스트 데이터를 손으로 구성하는 시간 없이 테스트 루프를 빠르게 돌릴 수 있어요.

원칙 11: 요청을 쪼개면 결과가 달라져요

"문서 검토해줘"는 너무 넓어요. LLM은 범위가 모호한 요청일수록 모든 차원을 동시에 얕게 훑는 경향이 있어요.

같은 문서에 대한 요청을 목적별로 나누면 결과가 달라져요.

같은 문서를 다섯 번 보내도 매번 다른 결과가 나와요. 요청마다 LLM이 집중하는 차원이 다르기 때문이에요.

왜 차이가 나는가: 넓은 요청은 LLM이 "검토"의 범위를 스스로 정의해요. 그 결과 눈에 띄는 것만 집어내는 얕은 패스가 돼요. 좁은 요청은 평가 기준이 명확하므로 그 기준 하나에만 집중하는 깊은 패스가 돼요.

이는 문서 검토에만 국한되지 않아요. 코드 리뷰도 마찬가지예요.

• "코드 리뷰해줘" → 표면적 검토
• "보안 취약점만 확인해줘" / "성능 병목 찾아줘" / "에러 핸들링이 누락된 곳 봐줘" → 차원별 깊은 검토

요청을 정확하게 할수록 에이전트는 쓸모있어져요.

메타 팁: 이 모든 작업을 에이전트에게 맡겨라

원칙 6부터 11까지 — 시스템 프롬프트 슬림화, 체크리스트 작성, 작업 분해, 스크립트화, 테스트 데이터 — 모두 직접 손으로 할 필요가 없어요. 에이전트에게 현재 상태를 보여주고 의견을 물어보세요.

"이 CLAUDE.md(또는 AGENTS.md) 너무 길어 보이는데 슬림화할 수 있을까?"
"이 작업 목록을 세션 단위로 쪼개서 체크리스트로 만들어줘."
"지금 시스템 프롬프트 파일에 트리거 구조를 도입하면 어떨까?"

LLM은 파일을 읽고 구조를 파악한 뒤 바로 제안하고 실행해요. 어떻게 나눌지 판단하는 것 자체가 LLM이 잘하는 일이에요. 하네스를 설계한 사람의 역할은 방향을 정하고 의견을 묻는 것 — 구체적인 파일 편집과 구조화는 에이전트에게 위임해 보세요.

전역 트리거로 워크플로우 전체를 자동화하세요:

원칙 6과 원칙 7을 매번 수동으로 요청할 필요 없이, 전역 시스템 프롬프트 파일에 트리거를 등록해두면 에이전트가 작업 흐름에서 자동으로 수행해요.

## 작업 트리거

사용자가 구체적인 작업(구현, 수정, 분석 등)을 요청하면:
1. 작업 시작 전 `checklist.md`를 생성한다:
   - 수행할 작업 목록
   - 각 항목의 완료 검증 기준 (어떻게 확인할지)
2. 작업 완료 후 각 검증 기준의 결과를 확인하고 출력한다
3. 다음을 판단하여 제안한다:
   - 문서 정리(CONTINUE.md) 후 새 세션 시작이 적절한지
   - 현재 세션에서 다음 작업을 계속하는 것이 나은지
   - 판단이 어려우면 사용자에게 직접 묻는다

이 트리거 하나로

• 작업 범위가 시작 전에 명확해져요 (체크리스트)
• 완료 기준이 사전에 합의돼요 (검증 항목)
• 세션 전환 판단을 에이전트가 능동적으로 제안해요.

"구체적인 작업" 요건을 명시하는 게 중요해요. 조건 없이 등록하면 짧은 질문이나 단순 조회에도 체크리스트가 생성되어 오히려 번거로워져요.

에이전트별 상세 설정 — Claude Code의 CLAUDE.md·Hooks·Skills 세 축은 Claude Code 3대 설정 축에서, Codex의 AGENTS.md·승인 모드·MCP 설정은 Codex 사용 가이드에서 다뤄요.