OpenCode 로컬 AI 에이전트의 첫걸음, 계획(Plan) — 가설 수립과 마일스톤 설계

AI 에이전트가 개발 도구를 사용할 때 가장 범하기 쉬운 실수는 앞뒤 상황을 파악하지 않고 무작정 파일 전체를 조회(`read`)하거나 전체를 검색(`grep`)하는 '도구 폭격(Tool Bombing)'입니다. 이는 컨텍스트 윈도우(Context Window)를 빠르게 소진시키고, 엉뚱한 방향으로 코드를 고쳐 시스템을 망가뜨리는 주원인입니다.

`open-code` 프로젝트와 커뮤니티는 이를 방지하기 위해 "도구를 호출하기 전에 반드시 가설을 수립하고 계획 문서를 명세화"하는 철저한 계획(Plan) 단계를 거칩니다.

① 계획(Plan) 단계의 핵심 철학

`open-code` 규칙 파일(`config/AGENTS.md`)에 기술된 계획 단계의 핵심 제약 사항은 다음과 같습니다.

Tool 호출 규율 (Plan 관련)
Plan 먼저, 그 다음 도구: 모르는 코드를 만났으면 무작정 grep/read 폭격을 날리기 전에 반드시 한 줄로 가설을 세우라.
3 step 이상 작업은 task list로 분해: 다 끝내고 한꺼번에 보고하지 말고 단계별로 알리라.

에이전트는 이 룰을 기반으로 행동을 시작하기 전, 자신의 추론 과정을 스스로 통제하는 시스템을 만듭니다.

② 계획(Plan) 단계의 전체 워크플로우

계획 단계는 단순히 해야 할 일을 나열하는 것을 넘어, 현 시스템의 성능을 실측하고 병목을 식별하는 정교한 분석 과정입니다.

각 단계별 상세 가이드 및 예시

1. 사용자 요구사항 수신

• 에이전트 루프 단계: 목표 정의 및 트리거 (입력 단계)
• 단계 설정 이유: 에이전트가 독자적으로 행동을 시작하기 전, 외부(사용자)로부터 최종 목표(Goal)를 부여받는 준비 구간입니다. 루프의 시작점 역할을 합니다.
• 쉬운 설명: 사용자가 해결하고 싶은 문제나 얻고자 하는 결과물을 에이전트에게 전달하는 단계입니다.
• 예시: "Qwen3.6 모델 기반 에이전트의 응답 속도가 75초 소요되는 지연을 최적화해줘."

2. 현 상황 및 병목 구간 실측

• 에이전트 루프 단계: 관찰 (Observation)
• 단계 설정 이유: 코드를 함부로 고치기 전에, 현재 시스템의 리소스 상태, 환경 설정, 에러 로그 등의 객관적인 사실을 수집하고 파악하는 관찰 과정입니다.
• 쉬운 설명: 문제가 왜 발생했는지 막연하게 추측하기 전에, 현재 시스템의 진짜 상태 데이터를 있는 그대로 측정해 보는 단계입니다.
• 예시: Ollama 서버의 `Context 길이`, `Flash Attention 활성화 여부`, `KV Cache Type` 등의 인프라 상태를 실측하여 오버헤드 요인을 분석합니다.

3. 1줄 가설 수립 및 탐색 범위 축소

• 에이전트 루프 단계: 계획 (Planning) - 가설 수립
• 단계 설정 이유: 수집한 관찰 데이터(사실)를 기반으로 "어떻게 해결할 것인가"에 대한 가정을 세우고, 작업할 영역을 좁히는 첫 번째 의사결정 단계입니다.
• 쉬운 설명: 분석한 데이터를 보고 "이 부분이 원인일 테니, 여기만 집중해서 고쳐보자" 하고 추측하며 탐색 범위를 좁히는 단계입니다.
• 예시: "가설: Ollama의 Context 크기를 제한하고 Flash Attention을 활성화하면 attention 연산 병목이 해결되어 속도가 단축될 것이다." (이후 탐색 범위를 관련 설정 파일로 좁힘)

4. 상세 실행 계획서 작성 (`docs/` 폴더)

• 에이전트 루프 단계: 계획 (Planning) - 설계
• 단계 설정 이유: 가설을 실행하기 위한 구체적인 작업 방법과 아키텍처 수정을 문서의 형태로 상세 설계하는 정교한 계획 수립 과정입니다.
• 쉬운 설명: 머릿속에 그린 해결 방법을 글로 풀어내어 "앞으로 이런 설계로 변경을 진행하겠다"는 구체적인 청사진을 작성하는 단계입니다.
• 예시: `docs/opencode-latency-opt.md` 계획 문서 생성 및 런타임 튜닝 세부 방안 기록.

5. 단계별 Task List 분해

• 에이전트 루프 단계: 계획 (Planning) - 태스크 분해
• 단계 설정 이유: 거대한 하나의 목표를 에이전트가 실행 가능한 최소 작업 단위(Task)로 나누어 마일스톤을 수립하는 세부 계획 고도화 과정입니다.
• 쉬운 설명: 큰 산을 한 번에 넘을 수 없듯이, 작업을 1단계, 2단계, 3단계처럼 작은 단계들로 쪼개어 차근차근 해결할 순서를 정하는 단계입니다.
• 예시: Phase 1(런타임 튜닝), Phase 2(에이전트 로직 최적화), Phase 3(인프라 마이그레이션) 등으로 실행 태스크를 분할.

6. 리스크 식별 및 롤백 가이드 정의

• 에이전트 루프 단계: 계획 (Planning) - 예외 처리 설계
• 단계 설정 이유: 최적화 시 발생할 수 있는 부작용이나 예외적인 실패 리스크를 파악하고, 비상시 이전 상태로 안전하게 복구할 계획을 미리 세우는 대비 단계입니다.
• 쉬운 설명: "만약 이 수정을 적용했다가 전체 서버가 먹통이 되면 어떻게 원래대로 되돌리지?"에 대한 비상 대응책을 미리 마련하는 단계입니다.
• 예시: KV 캐시 양자화 적용 시 모델 품질 저하 리스크가 있으면, 감지 즉시 이전 FP16 상태로 환원하고 컨텍스트 길이를 단축하는 등의 대응책 수립.

7. 사용자/시스템 실행 승인 확보

• 에이전트 루프 단계: 행동(Action) 진입 관문 / 최종 승인
• 단계 설정 이유: 계획 수립 단계를 모두 끝마치고, 실제 파일을 수정하거나 명령어를 실행하는 행동(Action) 단계로 넘어가기 위해 사용자나 시스템의 게이트키퍼로부터 동의를 구하는 게이트웨이입니다.
• 쉬운 설명: 준비한 완벽한 계획을 들고 가 사용자에게 "이제 진짜 수정을 시작해도 될까요?" 물어보고 승인을 받아내는 단계입니다.
• 예시: 작성된 Task List를 최종 브리핑한 뒤 사용자의 승인 피드백을 확보하고 도구를 실행. (승인 이후, 실질적인 코드 수정이라는 행동(Action)과 속도 개선을 확인하는 검증(Verification)이 이어집니다.)

③ 요약: 계획 단계가 주는 실질적인 효과

도구를 사용하기 전에 수립되는 정밀한 계획은 다음 두 가지 실질적인 가치를 제공합니다.

1. 컨텍스트 오버헤드 최소화: 불필요한 파일을 불러오지 않으므로 LLM에 전달되는 프롬프트의 품질과 속도가 비약적으로 향상됩니다.
2. 개발 예측 가능성 확보: 개발 도중 예상치 못한 자원 부족이나 롤백 상황이 발생했을 때 에이전트 스스로 복구가 가능해집니다.

---

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.