에이전틱 코딩은 기술 업계의 기준으로도 전례 없는 속도로 변화하고 있습니다. 온라인에서 구할 수 있는 튜토리얼과 리소스는 대부분 단순한 그린필드 시나리오에서의 개별 기능을 다루는 수준에 머물러 있습니다.
Bob을 만들고 다양한 산업 분야의 수많은 현장 실무자와 교류하면서, Bob의 효과와 사용 경험을 향상시키는 데 도움이 되는 개념들이 도출되었습니다.
이 개념들은 비주류 기술을 사용하는 복잡한 프로젝트에도 동일하게 적용됩니다.
개념 1: 사이클 — 탐색, 계획, 구현, 검증
에이전틱 소프트웨어 엔지니어링에서 가장 흔한 실패 패턴은 구조의 부재입니다. 대화의 흐름이 구조처럼 느껴지기 때문에 구현의 모든 단계를 하나의 채팅 대화에 담으려는 유혹이 생깁니다. 세션이 생산적으로 느껴지지만, 그 비용은 리뷰 단계에서야 비로소 드러납니다.
코드를 직접 손으로 작성하던 시절에는 그 자체로 구조가 생겼습니다. 구현 비용이 높았기 때문에 구현 전에 계획을 세우는 것이 직관적으로 합리적으로 느껴졌습니다. 타이핑하는 과정에서 이해가 쌓였고, 잘못된 가정은 그 과정에서 드러날 가능성이 높았습니다. AI 에이전트는 그 마찰을 제거했습니다. 이제 코드는 저렴해졌고, 그로 인해 구조에 대한 직관도 함께 사라졌습니다. 한때 느림의 부산물이었던 구조는 이제 의도적으로 만들어야 합니다.
이 사이클을 의도적으로 활용하면 구조를 제공할 수 있습니다:
- 탐색은 이해를 만들어냅니다
- 계획은 결정을 만들어냅니다
- 구현은 코드를 만들어냅니다
- 검증은 근거를 만들어냅니다.
이 사이클을 따르면 집중력을 유지하고, 구조화된 방식으로 더 빠르고 일관성 있게 목표를 달성하는 데 도움이 됩니다.
사이클을 한 번 도는 데 20분이 걸릴 수도 있고 3일이 걸릴 수도 있습니다. 하나의 사이클 안에 하위 사이클이 포함될 수 있으며, 각 단계에 할당되는 시간은 작업에 따라 크게 달라집니다.
사이클에 대한 자세한 설명은 아래 심층 분석: 사이클 실행에서 확인할 수 있습니다.
개념 2: 컨텍스트 윈도우가 희소 자원이다
컨텍스트 윈도우를 의식적으로 관리하는 것이 가장 높은 수익을 내는 습관입니다.
컨텍스트 윈도우란 무엇인가요?
모델은 상태를 갖지 않습니다. 채팅은 메모리가 있는 실행 중인 세션이 아닙니다. 매 턴마다 이전의 모든 메시지를 다시 전송하고 새 답변을 끝에 추가합니다. 컨텍스트 윈도우는 모델이 그 턴에서 받아들일 수 있는 최대 입력량입니다. Bob V2에서는 270k 토큰입니다 (컨텍스트 윈도우 관리).
윈도우는 첫 메시지 전부터 채워지기 시작합니다:
- 처음부터 로드되는 항목: Bob의 시스템 프롬프트, 활성 모드 설명, 저장소의
agents.md, 연결된 모든 Model Context Protocol (MCP) 도구 설명 (Bob의 MCP). - 세션 중 보이지 않게 추가되는 항목: 파일 읽기, 도구 결과, Bob이 불러오는 스킬 파일, 서브에이전트 출력.
윈도우가 가득 차면 Bob은 대화를 압축합니다. Bob은 지금까지의 대화를 요약본으로 대체하고 작업을 계속합니다. 이는 세션을 유지하면서도 의도적으로 손실이 발생하는 방식입니다. 어떤 세부 정보가 살아남을지는 Bob이 자동으로 결정하며, 살아남지 못한 정보는 어디에도 표시되지 않습니다. 두 번 압축된 세션은 요약의 요약 위에서 실행되는 것입니다.
단 하나의 MCP 호출이 수만 개의 토큰을 반환할 수 있으며, 연속적인 파일 읽기는 세션 초반에 논의된 내용을 희석시킵니다. 모드 설명, 규칙 파일, MCP 서버도 더 느리고 덜 눈에 띄는 방식으로 동일한 영향을 줍니다. Bob은 출처별로 윈도우를 분석해 보여주며, 설정이 커질수록 그 분석을 다시 살펴볼 가치가 있습니다.
Bobcoin은 주로 토큰 단위로 계산됩니다. 따라서 대화 비용은 대화 길이에 따라 기하급수적으로 증가합니다. 긴 대화는 짧은 대화보다 훨씬 많은 Bobcoin을 소모합니다! (Bobcoin 문서)
컨텍스트 윈도우에 맞서지 말고 활용하기
- 작업을 별도의 대화로 분리하세요. 하나의 작업, 하나의 세션. 코드에서의 단일 책임 원칙과 동일한 논리입니다. 대화는 하나의 존재 이유를 가져야 합니다. 예를 들어 "컴포넌트 X의 아키텍처 다이어그램 그리기" 또는 "기능 Y의 구현 계획 작성하기"처럼요. 컨텍스트 윈도우 안에 있는 모든 것이 다음 결과에 영향을 미칩니다. 잘 안 된 접근법도 포함해서요. 한번 막힌 세션은 계속 막히는 경향이 있습니다. 실패한 시도들이 여전히 남아 있고, 모델은 그것들을 이 작업이 어떤 모습인지에 대한 근거로 읽기 때문입니다 (컨텍스트 오염).
- Bob과 논쟁하는 대신 롤백하세요. 대화가 원하지 않는 방향으로 흘러갈 때는 마지막으로 좋았던 메시지로 롤백하고, 그 메시지를 수정한 후 계속 진행하세요. 이렇게 하면 Bob이 로컬에서 변경한 내용도 모두 취소되어 컨텍스트 윈도우를 작고 깔끔하게 유지할 수 있습니다 (롤백).
- 보존할 가치가 있는 것은 채팅이 아닌 파일에 저장하세요. 계획, 발견 사항, 결정은 파일에 속합니다. 동료는 마크다운 문서를 검토하고 새 세션에 전달할 수 있지만, 채팅 로그는 그 어느 것도 할 수 없습니다.
- 서브에이전트는 대량 작업을 컨텍스트 윈도우 밖에서 처리합니다. Bob이 필요할 때 알아서 실행하며, 발견 사항만 돌아옵니다. 아무도 출력을 읽을 필요가 없는 작업이라면 직접 요청해도 됩니다 (서브에이전트).
- 컨텍스트 윈도우에 무엇이 들어가는지, 그것이 가치를 더하는지 주의를 기울이세요. 다음 주제에서 다루듯이, 가이드와 센서를 정기적으로 점검하고 개선하는 데 시간을 투자하세요.
개념 3: 두 가지 종류의 구성 요소 — 가이드와 센서
장기 프로젝트에서 코드베이스가 나아지느냐 나빠지느냐는 Bob보다 Bob의 작업을 형성하고 출력을 검증하는 것들에 더 크게 달려 있습니다. 사용할 수 있는 구성 요소는 많습니다: 규칙, 스킬, 모드, 훅, 서브에이전트, 외부 린터, 리뷰 에이전트. 이들 거의 모두 두 가지 역할 중 하나를 수행합니다.
- 가이드는 Bob이 작업하기 전이나 작업하는 동안 방향을 안내합니다 (피드포워드). 규칙, 스킬, 모드가 모두 가이드에 해당합니다.
- 센서는 Bob이 행동한 후 피드백을 보고합니다 (피드백). 테스트, 린터, 타입 체커, 인터랙티브 브라우저 세션, 리뷰 에이전트가 모두 센서에 해당합니다.
1. 가이드
Bob에게 작업 방향을 안내하기 위해 제공되는 것은 모두 가이드입니다. 세 가지 주요 구성 요소가 있으며, 이들은 입력한 프롬프트에 추가로 텍스트를 컨텍스트 윈도우에 넣는 방식으로 작동합니다. 차이점은 그 텍스트가 언제 도착하고 무엇이 트리거하느냐에 있습니다.
- 규칙은 항상 활성화되어 있습니다.
저장소 루트의
agents.md가 주된 규칙 파일이며, 핵심 조언은 짧게 유지하는 것입니다. 모든 줄이 매 턴마다 주의를 차지하기 때문에, 규칙 파일이 길어지면 개별 규칙을 따르는 Bob의 능력이 떨어집니다 (규칙). - 모드는 사용자가 활성화합니다. 기본 제공 모드는: Ask는 읽기 전용입니다. Plan은 계획 프로세스를 진행하고 결과를 Agent에 넘기며, Agent가 실제 행동을 취합니다. 커스텀 모드를 쉽게 추가할 수 있습니다 (모드, 커스텀 모드 추가).
- 스킬은 Bob이 관련성이 있다고 판단할 때 활성화합니다. 짧은 스킬 설명만 항상 활성화되어 있고, 스킬 본문은 필요할 때만 컨텍스트에 로드됩니다. 그래서 스킬은 토큰 효율이 매우 높습니다 (스킬).
규칙 파일의 모든 내용은 해당 턴에 필요하든 아니든 매 턴 토큰을 소모합니다. 따라서 최소한으로 유지하고, 나머지는 필요할 때까지 기다리게 하세요.
2. 센서
Bob이 생산한 작업에 대한 피드백을 제공하는 것은 모두 센서입니다. 어떤 신호가 유용한지는 코드베이스와 스택에 따라 달라지므로, 갖춰야 할 센서 세트는 프로젝트마다 다르며 실제로 조립하는 데 상당한 노력이 필요합니다. 가장 가치 있는 센서는 기계적으로 실행 가능하며 구현 단계에서 Bob이 직접 실행할 수 있는 것입니다. 센서는 두 가지 범주로 나눌 수 있습니다.
- 계산적 센서는 결정론적입니다: 테스트, 린터, 타입 체커, 컴파일러. 결과는 정확하고 반복 가능하며, Bob이 자주 실행할 수 있을 만큼 저렴합니다. 커버리지는 팀이 구축하고 유지하는 시스템의 범위로 제한됩니다.
- AI 기반 센서는 유연하고 비결정론적입니다. 리뷰 에이전트는 의도와 린터가 규칙으로 다루지 못하는 것들을 읽어냅니다. 출력은 측정이 아닌 판단입니다. 실행마다 달라지며, 비용과 소요 시간으로 인해 사용 빈도가 제한됩니다 (코드 리뷰).
이를 연결하는 방법은 마찰 정도에 따라 여러 가지가 있습니다:
- 훅은 마찰이 가장 낮은 결정론적 옵션입니다. 검사가 Bob이 관련성을 판단하든 아니든 매번 고정된 시점에 실행됩니다. 훅 문서를 참조하세요.
- 스킬은 가이드로 자주 사용되지만, 리뷰를 실행하는 스킬은 센서이며, 비결정론적 검사를 추가하는 가장 낮은 마찰의 방법입니다. 스킬 문서를 참조하세요.
- **지속적 통합(CI)**은 파이프라인에 리뷰어 에이전트를 배치하여 한 명의 개발자가 아닌 팀 전체를 위해 모든 pull request에서 실행됩니다. PR 리뷰 에이전트 실행 영상을 참조하세요.
심층 분석: 사이클 실행
단계 경계는 컨텍스트 경계이기도 합니다. 단계를 구분해야 하는 실용적인 이유가 바로 이것입니다: 탐색 대화는 코드가 작성되는 대화에 있을 이유가 없습니다.
1. 탐색
탐색은 역할과 작업에 따라 크게 달라집니다. 새 코드베이스에 온보딩하는 것일 수도 있고, 대규모 리팩토링의 영향 범위를 추정하는 것일 수도 있습니다. 몇 가지 예시:
- 변경하기 전에 Bob이 기존 시스템의 아키텍처 다이어그램을 만들도록 하세요. 아키텍처 다이어그램 생성 튜토리얼이나 같은 내용의 영상을 참조하세요.
- 두 가지 관점에서 맞춤형 시작 가이드를 요청하세요. 제품을 이용하는 사용자 관점과 코드를 다루는 개발자 관점으로 한 번씩. 전문성과 작업에 대한 정보를 제공하면 문서를 더 잘 맞출 수 있습니다 (코드베이스 검사).
- IBM Z 및 IBM i에서는 플랫폼 전용 옵션을 활용하세요. 해당 시스템에서의 탐색 문제는 다르며, 프리미엄 패키지에 제공되는 특화 도구로 큰 이점을 얻을 수 있습니다. Z용 프리미엄 패키지 (문서)와 IBM i용 프리미엄 패키지 (문서)를 참조하세요.
탐색에는 삭제할 것을 만드는 작업도 포함될 수 있습니다. 이제 구현이 저렴해졌기 때문에, 좁은 범위의 프로토타입이 어떤 접근법이 코드베이스와 맞는지 확인하는 가장 빠른 방법입니다. Kent Beck은 25년 전에 이것을 스파이크 구현이라고 불렀으며, 원칙은 동일합니다: 무언가를 배우기 위해 만들고, 배운 것은 남기고, 코드는 버리세요.
저렴한 구현은 아키텍처와 코드 품질의 가치를 낮추는 것이 아니라 오히려 높입니다. 이제 작동하지만 잘못된 코드를 대량으로 만들어내는 것이 쉬워졌기 때문입니다.
2. 계획
계획 단계가 가장 큰 레버리지가 있는 곳입니다. 계획이 올바르게 된 모든 것은 두 배로 돌아옵니다: 한 번은 구현에서, 그리고 또 한 번은 변경 사항이 작성자의 손을 떠나 동료가 리뷰할 때.
좋은 계획에 필요한 것:
- 짧고 정확하게, 둘 다. 계획은 읽혀야 합니다.
- 불확실한 부분을 포함해 의도한 결과를 명시적으로. 무엇이 알려지지 않았는지 파악하는 것이 작업의 대부분이며, 그것을 밝혀내는 것이 나머지입니다.
- 파일에 저장. 계획은 채팅 세션에 살면 안 됩니다.
계획을 만드는 방법은 많지만, 내장된 Plan 모드가 시작하기 가장 쉬운 곳입니다 (이 튜토리얼 참조).
Plan 모드는 동의하도록 설계되어 있어 빈 부분을 채우는 경향이 있습니다. 많은 경우에 빠른 반복을 가능하게 하지만, 때로는 더 엄격함이 필요합니다. 잘못된 가정에 대해 반박하지 않고 그 주변에 능숙한 계획을 세울 수 있습니다.
계획에 이의를 제기하는 전용 스킬 — 예를 들어 Matt Pocock의 grill-me — 은 가정이 코드가 되기 전에 검토를 받는 가장 저렴한 방법입니다.
스펙 주도 개발(SDD)에 대해. 이 용어는 광범위한 영역을 다루며 아직 변화 중입니다. 사람들은 이를 예스/노 결정으로 다루는 경향이 있지만, 스펙트럼에 가깝습니다:
- 스펙 우선: 계획이 구현보다 먼저 옵니다. 이는 거의 협상 불가능한 원칙입니다.
- 스펙 앵커: 스펙이 구현 후에도 남아 있으며, 문서이자 구현이 충족해야 할 기준으로 기능합니다.
- 스펙 소스: 스펙이 소스 파일입니다. 개발자가 스펙을 편집하고, 코드는 직접 편집하지 않습니다.
어느 수준이 적합한지는 팀, 코드베이스의 중요도/성숙도, 산업에 따라 다릅니다. 높은 수준의 SDD에 따르는 오버헤드는 빠른 반복에는 부담이 될 수 있습니다. AI보다 수십 년 전부터 스펙 주도 개발을 해온 자동차 산업에서는 SDD가 기존 관행에 매우 잘 맞습니다.
3. 구현
구현은 간단한 단계이며, Bob이 거의 대부분을 처리합니다.
Bob의 작업을 지켜보고 명확히 하기 위해 중간에 개입하는 것은 선택 사항이며 종종 유용합니다. 개입 빈도를 신호로 삼으세요: 계속 개입하게 된다면 문제는 계획에 있으며, 계속 수정하는 것보다 돌아가는 것이 해결책입니다.
전체 구현을 버리고 Plan 모드로 돌아가는 것을 두려워하지 마세요. 코드는 저렴한 부분입니다.
4. 검증
검증은 두 가지 범주로 나뉩니다: 자동 검증과 수동 검증.
자동 검증은 Bob이 사용할 수 있는 센서 또는 훅을 통해 강제되는 센서에 의해 수행됩니다. 이는 인간의 개입 없이 구현 단계에서 자주 실행됩니다. 주요 범주와 몇 가지 일반적인 예시는 다음과 같습니다:
- 유효성: 컴파일, 타입 체크, 파싱이 되는가?
- 측정: 통과/실패, 타입 커버리지
- 도구:
tsc,mypy,cargo check,javac
- 동작: 올바른 일을 하는가?
- 측정: 통과율, 브랜치 커버리지
- 단위 테스트, 통합 테스트, 엔드-투-엔드 테스트
- 도구:
pytest,Jest,Playwright,Stryker
- 유지보수성: 이 코드는 보존할 가치가 있는가?
- 측정: 복잡도, 중복, 경계 위반
- 도구: ESLint, Ruff, Lizard, ArchUnit
- 보안: 이 코드는 안전한가?
- 측정: 심각도별 발견 사항, CVE
- 도구: Semgrep, CodeQL, gitleaks,
npm audit
이를 통해 Bob이 스스로 실수를 발견하고 구현 단계에서 품질을 향상시킬 수 있습니다. 좋은 테스트 커버리지는 회귀에 대한 필수적인 보호 장치입니다: Bob이 아무것도 망가뜨리지 않았음을 보장합니다.
이 사이클에서 검증은 루프 끝의 별도 단계로 나열되어 있으며, 이는 주로 수동 검증을 의미합니다. 수동 검증은 변경 사항을 실행하고 관찰된 동작을 계획이 명시한 동작과 비교하는 것에서 시작합니다. 불일치는 대부분 두 가지 원인 중 하나로 좁혀집니다:
- 구현이 계획에서 벗어났습니다. 수정은 코드에 있습니다.
- 계획이 의도한 것을 반영하지 않습니다. 계획을 다듬어야 합니다. 이 경우가 훨씬 더 흔합니다.
따라서 수동 검사는 계획과 구현을 동시에 테스트합니다.
CI/CD 파이프라인에서도 추가적인 검증이 이루어져야 합니다. 이는 소프트웨어 엔지니어링에서 잘 확립된 관행이지만, 헤드리스 코딩 에이전트를 사용하여 개선할 수 있습니다. 한 가지 예: Bob Shell을 통해 실행되는 모든 pull request에 대한 자동 리뷰는 인간 리뷰어를 대체하는 것이 아니라 보완합니다. PR 리뷰 에이전트 실행 영상과 Bob Shell 비대화형 실행 문서를 참조하세요.
팀에서 작업하기
앞선 섹션의 모든 내용은 한 명의 개발자의 내부 루프를 설명합니다. 외부 루프는 변경 사항이 리뷰 대기열로 이동할 때 시작됩니다. 이제 모든 diff는 더 빠르게 도착하지만 그 이유에 대한 설명은 적으며, 리뷰어는 읽어야 할 것은 더 많고 그것을 읽을 컨텍스트는 더 적습니다.
근거는 작업과 함께 전달되어야 합니다. 왜가 어떻게보다 더 중요해졌습니다. 어떻게는 더 이상 비싼 부분이 아니기 때문입니다.
실제로 이는 계획이 변경 사항과 함께 전달된다는 것을 의미합니다: 팀은 pull request에 첨부하거나 리뷰와 함께 원래 이슈에 추가합니다. 방법은 사용하는 도구에 따라 달라집니다.
외부 루프가 팀의 프로세스에 미치는 영향은 별도의 주제이며, 이후 포스트에서 다룰 예정입니다.
프롬프팅에 대한 몇 가지 생각
지난 몇 년간 LLM을 올바르게 프롬프트하는 것에 큰 중점이 두어졌고, 그로부터 "프롬프트 엔지니어"라는 직군 범주가 등장했습니다. 현재는 많은 프롬프팅이 하네스 내부에서 처리됩니다. 특화된 프롬프팅 기법의 중요성은 방법론적 접근의 중요성에 밀려 줄어들었습니다. 다음은 몇 가지 지침입니다:
- 반복이 프롬프팅을 이깁니다. Bob이 요청한 것과 다른 일을 할 때, 롤백하고 그것을 유발한 메시지를 다시 작성하세요. 앞으로 수정하면 틀린 답변, 그에 대한 불만, 재시도가 모두 윈도우에 남게 됩니다.
- 방법론이 프롬프팅을 이깁니다. 프롬프트는 하나의 세션에 한정됩니다. 규칙 파일이나 Bob이 직접 실행할 수 있는 검사는 그것을 만들어낸 세션 이후의 모든 세션에서 계속 작동하며, 이것이 여기서 축적되는 유일한 종류의 투자입니다.
- 시니어 엔지니어가 받을 만한 브리핑을 Bob에게 제공하세요. 유능한 동료는 막연한 작업을 받으면 완료 기준이 무엇인지, 무엇을 건드려도 되는지 물어볼 것입니다. Bob은 묻지 않으니 메시지에 둘 다 넣으세요.
- 하지 말아야 할 것이 아닌 해야 할 것을 말하세요. "클래스 컴포넌트를 사용하지 마세요"는 하나의 옵션을 배제하고 나머지 공간을 열어두므로, Bob은 남은 것에서 선택하게 되어 또 다른 추측이 됩니다. 대신 목표를 직접 명시하면 — 훅이 있는 함수 컴포넌트 — 한 번에 해결됩니다.
- 두 번 이상 반복되는 지시는 파일에 속합니다. 그것이
agents.md와 스킬의 존재 이유입니다. - 더 자세한 프롬프팅 지침은 효과적인 프롬프트 작성 튜토리얼에서 확인할 수 있습니다.
핵심 요약
- 구조의 부재가 가장 큰 문제입니다. 탐색 → 계획 → 구현 → 검증 사이클을 따르면 집중력을 유지하고 더 빠르고 일관성 있게 목표를 달성하는 데 도움이 됩니다.
- 컨텍스트가 희소 자원이며, 단계는 컨텍스트 경계입니다. 탐색 대화를 구현으로 가져가지 마세요.
- 계획이 리뷰 산출물입니다. 계획을 리뷰하는 것이 diff를 리뷰하는 것보다 낫습니다. 작성자와 리뷰어 모두에게.
- 보존할 가치가 있는 것은 채팅을 떠납니다. 계획, 결정, 발견 사항은 파일에 속합니다. 파일은 diff를 볼 수 있고, 리뷰할 수 있고, 버전 관리할 수 있고, 다른 에이전트에게 전달할 수 있습니다.
- 검증은 기계적으로 실행 가능해야 합니다. 즉, 나중에 발견하는 것이 아니라 계획 단계에서 설계해야 합니다.
참고 자료 및 추가 읽기
- Simon Willison, 에이전틱 엔지니어링 패턴
- Birgitta Böckeler, 하네스 엔지니어링
IBM Bob 문서 및 튜토리얼: