Book-Length Introduction

이제 중요한 것은 “어떤 모델인가”보다
“어떤 하네스로 일하게 만드는가”입니다

사내 개발자가 에이전트를 많이 이해하고 많이 셋업해 실제 생산성을 올리려면, 감탄문보다 기술적인 뒷받침이 필요합니다. 왜 이 모델이 이 수준의 코딩을 할 수 있는지, 어떤 설정이 안전을 보장하는지, 왜 MCP와 hooks와 rules가 필요한지까지 이어져야 도입이 됩니다.

과거 발전 과정: ChatGPT 출시부터 지금까지 4년의 흐름

AI 코딩 도구의 실질적인 시작점은 2022년 11월 30일 ChatGPT 출시입니다. 그 이전의 자동완성과 연구 단계 모델들은 일부 개발자만 알던 영역이었지만, ChatGPT 이후로 일반 사용자가 처음으로 LLM 과 직접 대화하면서 “AI 와 함께 코드를 짜는 일” 이 모든 사람의 일이 됐습니다. 이 4년의 흐름을 한눈에 보는 것이 이번 섹션의 목표입니다.

현재 가장 핫한 흐름: 모델보다 작업 환경이 중요해졌습니다

2026년의 AI 코딩은 “좋은 모델 하나를 고르는 문제” 로 설명하기 어렵습니다. 실제 체감 생산성은 모델 자체보다 그 모델을 둘러싼 작업 환경의 품질에 더 크게 좌우됩니다. 메모리와 문서 인용, 자동화된 검증, 도구 연결, 조직 정책이 모두 여기 들어갑니다. 같은 모델을 써도 누군가는 매우 강한 결과를 얻고 누군가는 실망하는 이유가 여기 있습니다.

지금 뜨는 조합은 무엇인가

지금 가장 실용적인 조합은 대체로 비슷합니다. 메인 세션에는 Claude Code 또는 Codex 같은 강한 AI 코딩 도구를 두고, 문서 인용에는 Context7, UI 검증에는 Playwright MCP, 작업 추적에는 Linear 또는 GitHub, 팀 문서와 협업에는 Slack 또는 Atlassian 같은 외부 연결을 붙입니다. 여기에 규칙과 훅으로 안전 장치를 추가하고 build · test · verify 스크립트로 품질을 닫는 구조가 현재 가장 재현성이 높습니다.

특히 오픈 모델의 실용화는 중요한 변화입니다. 예전에는 오픈 모델이 “보조적인 분석 도구”에 가까웠다면, 지금의 강한 30B급 coder 모델은 명확한 계약과 좋은 하네스 아래에서 실제 구현과 구조 정리, 테스트 보강까지 감당하는 구간으로 올라왔습니다. 그래서 앞으로는 “폐쇄형 vs 오픈형”의 이분법보다, 어떤 역할에 어떤 모델을 배치하느냐가 더 중요해집니다.

왜 “하네스 엔지니어링”이라고 부르는가

하네스는 모델을 감싸는 운영 구조입니다. 즉흥적인 vibe coding 과 달리, 구조화된 하네스는 메모리, 스킬, 서브에이전트, 정책, 훅, 검증 루프를 설계합니다. 이것은 프롬프트 팁이 아니라 소프트웨어 엔지니어링의 새로운 하위 분야에 가깝습니다.

이 표현을 굳이 “엔지니어링”이라고 부르는 이유는 두 가지입니다. 첫째, 재현 가능성이 있어야 합니다. 같은 저장소, 같은 규칙, 같은 검증 명령이라면 다른 개발자나 다른 세션도 비슷한 품질을 내야 합니다. 둘째, 유지보수가 가능해야 합니다. 실패가 났을 때 “프롬프트를 좀 더 잘 써 보자”가 아니라, 어느 층에서 고쳐야 하는지 분리해서 다뤄야 합니다.

설계 단계의 7가지 결정

하네스를 처음 설계하는 팀이 거의 항상 부딪히는 7가지 결정 지점입니다. 각각은 정답이 아니라 trade-off 입니다. 어느 쪽을 선택하든 그 선택의 이유를 문서화해 두는 것이 가장 중요합니다.

• 1

  단일 vs 멀티 에이전트

  메인 에이전트 하나로 충분히 끝낼 수 있는 일에는 단일 에이전트가 더 빠르고 안정적입니다. 도구가 10개 이상 겹치거나 명확히 분리된 도메인이 있을 때만 멀티 에이전트로 분할하시는 편이 안전합니다.

• 2

  ReAct vs Plan-and-Execute

  ReAct 는 매 단계 reasoning 과 action 을 번갈아 합니다 — 유연하지만 단계당 비용이 듭니다. Plan-and-Execute 는 계획과 실행을 분리해 비용을 줄이지만 적응성이 떨어집니다. 두 패턴은 작업 유형에 따라 골라 쓰시면 됩니다.

• 3

  컨텍스트 관리 전략

  시간 기반 정리, 대화 요약, 관찰 마스킹, 구조화된 노트, 서브에이전트 위임 — 다섯 가지 패턴 중에 작업 길이와 도구 출력량에 맞는 조합을 고르시면 됩니다. 컨텍스트는 “많이” 가 아니라 “신호 대 노이즈 비율” 이 핵심입니다.

• 4

  검증 루프 설계

  결정적 검증(테스트, lint, 타입 체커) 은 빠르고 명확합니다. 추론형 검증(LLM-as-judge) 은 의미상의 오류를 잡지만 지연이 더 큽니다. 두 가지를 같은 파이프라인에 같이 두는 것이 안전합니다.

• 5

  권한과 안전 정책

  허용형(빠르지만 위험) vs 제한형(안전하지만 느림) 의 trade-off 입니다. 사내 도입에는 일반적으로 제한형 기본값에서 시작해, 안정화된 작업만 점진적으로 자동 승인을 늘리시는 편이 안전합니다.

• 6

  도구 범위 설정

  도구가 많을수록 선택이 어려워져서 결과가 오히려 나빠지는 경우가 많습니다. 매 단계에 필요한 최소 도구 세트만 노출하시는 편이 정확성이 더 높습니다. lazy loading, 단계별 도구 분리도 같은 맥락입니다.

• 7

  하네스 두께

  얇은 하네스는 모델 능력에 의존하고, 두꺼운 하네스는 코드로 흐름을 명시합니다. 모델이 좋아질수록 얇은 하네스가 유리해지므로, 쪽수보다 “지금 이 모델 세대에서 안정적인가” 를 기준으로 삼으시면 됩니다.

운영 시스템으로서의 하네스

이번에 살펴본 codexmaster 문서 구조에서 가장 배울 점은, 하네스를 기능 모음이 아니라 운영 시스템 으로 설명한다는 것입니다. 이 관점은 우리 사이트에도 잘 맞습니다. 실제로 좋은 하네스는 단순한 prompt template이 아니라, 실행 순서와 검증, 계측, 디버깅, 복구를 묶은 시스템입니다.

실무에서 이 시선 전환은 꽤 큽니다. 예를 들어 “왜 어떤 개발자는 잘 쓰고 어떤 개발자는 못 쓰는가”를 개인 역량 문제로 돌리기 쉽지만, 실제로는 공통 문서, 공통 검증, 공통 safety bar, 공통 MCP 세트가 없는 팀에서 결과 편차가 커집니다. 반대로 이 층이 잘 설계된 팀은 프롬프트를 조금 덜 잘 써도 평균 품질이 안정됩니다.

측정 체계도 함께 있어야 합니다

`codexmaster` 에서 또 좋았던 부분은 metrics 문서를 별도로 둔 점입니다. 우리도 같은 관점이 필요합니다. 에이전트 도입은 체감이 아니라 수치로 봐야 합니다.

• 정확성: 결과가 실제로 맞는가
• 완전성: 요청된 범위를 다 수행했는가
• 명료성: 다른 개발자가 결과를 이해하고 이어받을 수 있는가
• 효율성: 과도한 복잡도 없이 끝냈는가
• 신뢰성: 비슷한 작업에서 일관되게 동작하는가
• 제약 준수: rules, hooks, approval, security bar 를 지켰는가

디버깅도 playbook 화해야 합니다

에이전트가 낸 이상한 결과를 “모델이 원래 그래”로 넘기지 말고, 실패 재현 → 증거 수집 → root cause → 최소 수정 → 검증으로 이어지는 디버깅 playbook을 가져야 합니다. 이 부분도 앞으로 handbook과 playbook에 더 확장할 가치가 큽니다.

결국 하네스는 코드 생성기를 넘어 일종의 개발 운영체제 역할을 하게 됩니다. 문맥을 불러오고, 작업을 분배하고, 위험을 제한하고, 실행 결과를 다시 시스템에 학습시키는 구조가 있어야 장기적으로 팀 생산성이 올라갑니다.

모델을 어떻게 해석해야 하나: 코딩과 아키텍처 능력의 현실적 레벨

모델은 계속 경량화되고 빨라지고 있습니다. 중요한 것은 벤치마크 숫자를 외우는 것이 아니라, 그 모델이 어느 수준의 코딩과 설계 판단까지 감당할 수 있는지 읽는 것입니다.

벤치마크를 조직에 어떻게 번역할 것인가

사내 도입 관점에서 중요한 것은 “어떤 모델이 1등인가”가 아닙니다. 실제 질문은 이렇습니다. 이 모델을 junior 개발자 보조처럼 쓸 것인지, reviewer처럼 쓸 것인지, 설계 파트너처럼 쓸 것인지, 문서 요약과 검색 전용으로 둘 것인지. 즉, 모델 선택은 언제나 역할 설계와 같이 가야 합니다.

또 하나 중요한 점은 비용 구조입니다. 메인 세션을 최고 모델로 두는 것은 꽤 자주 정당화되지만, reviewer나 verifier까지 모두 비싼 모델로 두는 것은 보통 과합니다. “메인 하나 + 작은 서브에이전트 여러 개” 구성이 실제 조직에서는 가장 오래 가는 경우가 많습니다.

사내 도입은 도구 소개가 아니라 작업 방식 표준화로 가야 합니다

개발자가 많을수록 “각자 알아서 잘 쓰기”는 실패합니다. 공통 검증 명령, 공통 AGENTS.md 구조, 공통 safety bar, 공통 MCP 세트, 공통 도입 순서가 먼저 있어야 합니다.

이건 단순한 교육 문제가 아닙니다. 팀에서 “하네스를 어떻게 표준으로 제공할 것인가”의 문제입니다. 예를 들어, 누군가는 hooks를 쓰고 누군가는 안 쓰고, 누군가는 다른 verify 명령을 쓰고, 누군가는 로컬에서만 통과하는 스크립트를 쓰면 에이전트 품질보다 협업 비용이 먼저 커집니다. 그래서 도입은 항상 문서와 설정을 함께 배포하는 방식으로 가야 합니다.

# 사내 도입 예시
1. 루트 CLAUDE.md / AGENTS.md 초안 배포 (두 도구 모두)
2. 표준 verify 스크립트와 build 명령 고정
3. reviewer / verifier / docs researcher 서브에이전트 제공
4. Playwright + Context7 MCP 기본 세트 제공
5. 팀별로 Figma / Linear / Slack / Atlassian MCP 선택 추가
6. 분기별로 모델과 rules / hooks / skills 갱신
7. 회고 지표: build 성공률, PR 리뷰 속도, 회귀 감소, 재작업 시간 감소

권장 도입 단계

Side-by-side

Claude Code 와 Codex — 같은 개념, 다른 이름

이 사이트의 카탈로그는 Claude Code 와 Codex 두 도구를 모두 지원합니다. 기능적으로 두 도구는 거의 같은 일을 합니다. 다만 파일 이름, 설정 문법, 슬래시 명령, 안전 장치의 표현 방식이 조금씩 다릅니다. 같은 운영 사상을 두 도구에 어떻게 옮기는지가 핵심이며, 이 섹션은 그 mapping 과 차이점을 한 번에 정리합니다.

같은 개념의 자리

둘 다 똑같이 적용되는 공통 패턴

• 1팀의 사실은 모두 메모리 파일(CLAUDE.md / AGENTS.md)에 박는 것이 첫 단계입니다. Claude Code 와 Codex 두 도구 모두 세션 시작 시 자동 로드합니다.
• 2위험 명령은 declarative rules + dynamic hooks 두 층으로 막습니다. 한 층만 믿으면 우회 가능합니다.
• 3reviewer / verifier / docs-researcher 처럼 좁은 역할의 read-only 서브에이전트를 먼저 만드는 것이 가장 효과적입니다.
• 4MCP 서버는 두 도구가 공유합니다. Playwright MCP 하나 설치하면 Claude Code 와 Codex 양쪽에서 같이 쓸 수 있습니다.
• 5검증 루프 (build, test, lint, eval) 가 끝나야 작업 완료입니다. 두 도구 모두 verify-before-completion 패턴이 권장됩니다.
• 6세션 시작 hook 으로 저장소 컨텍스트(검증 명령, 운영 원칙)를 매번 주입하면 컨텍스트 누락이 줄어듭니다.
• 7파일 경로 기반 path-specific 규칙을 분리해 두면, 모듈별로 다른 안전 기준을 적용할 수 있습니다.
• 8분기별로 모델, MCP, rules, hooks, skills 를 같이 갱신하는 운영 리듬이 필요합니다.

의미 있는 차이점

세부 문법 차이는 많지만, 운영에 영향을 주는 지점만 골랐습니다. 도구를 옮기거나 둘을 동시에 쓸 때 가장 자주 부딪히는 지점들입니다.

나란히 두는 도입 설정 예시

같은 팀 안전 기본값을 두 도구에 어떻게 옮기는지 한 화면에 둡니다. 두 파일은 같은 사상을 표현하지만 문법이 다릅니다.

{
  "permissions": {
    "allow": [
      "Bash(./gradlew test)",
      "Bash(pnpm build)",
      "Read(**/*.md)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force)",
      "Read(.env)"
    ]
  },
  "hooks": {
    "SessionStart": [
      { "command": ".claude/hooks/session_start.py" }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": ".claude/hooks/pre_bash_guard.py"
      }
    ]
  }
}

# .codex/config.toml
model = "gpt-5.4"
sandbox_mode = "workspace-write"
approval_policy = "on-request"

[features]
codex_hooks = true
multi_agent = true

[agents]
max_threads = 6
job_max_runtime_seconds = 1800

# .codex/rules/default.rules
prefix_rule("rm -rf", forbidden)
prefix_rule("git push --force", forbidden)
prefix_rule("git push", prompt)

# .codex/hooks.json
{
  "SessionStart": [{ "command": ".codex/hooks/session_start.py" }],
  "PreToolUse": [
    { "matcher": "Bash", "command": ".codex/hooks/pre_bash_guard.py" }
  ]
}

어느 쪽을 먼저 시작해야 하는가

더 자세한 비교는 /architecture/claude-vs-codex 페이지의 전체 비교 표를, 실제 설정 적용은 /playbook/setup-claude-code 와 /playbook/setup-codex 를 참고해 주십시오.

이 사이트를 어떻게 읽으면 되는가

이 핸드북은 설명의 중심축이고, 나머지 페이지들은 각 층을 더 깊게 파는 역할입니다. 아래 순서를 따라가면 한 번의 세션에서 이해가 끊기지 않습니다.

앞으로의 방향: 모델 경쟁이 작업 환경 경쟁으로 옮겨갑니다

모델 자체의 지능 향상은 앞으로 1~3년도 계속됩니다. Epoch AI 의 컴퓨트 추정에 따르면 최상위 학습 컴퓨트는 매년 4~5배 가까이 늘어 왔고, 단기간에 이 곡선이 꺾일 신호는 보이지 않습니다(epoch.ai). 그런데 같은 모델을 같은 회사 안에서 두 팀이 써도 체감 생산성이 크게 갈리는 현장을 보면, 결국 차이는 모델 자체가 아니라 그 모델을 둘러싼 작업 환경 — 즉 하네스 — 에서 벌어집니다.

그래서 다음 1~3년의 경쟁은 “더 큰 모델”이 아니라 다음 다섯 가지 운영 영역에서 결정될 가능성이 높습니다.

1. 작업 길이가 늘어나면 감독·검증이 새 병목이 됩니다

METR 의 2025년 “Measuring AI Ability to Complete Long Tasks” 연구는 모델이 자율적으로 끝낼 수 있는 작업의 길이가 지난 5년 동안 약 7개월마다 두 배가 됐다고 보고했습니다(metr.org). 이 곡선이 계속된다면 다음 세대에서 가장 먼저 무너지는 것은 단순 자동완성이 아니라 장기 작업을 사람이 어떻게 감독하고 검증할 것인가 입니다. 모델 벤치마크 숫자로는 이 문제가 잡히지 않고, 메모리 운영, 검증 루프, 관측 인프라처럼 하네스 측 변수로만 잡힙니다.

2. 강한 작은 모델의 역할 고정

모든 작업을 최상위 모델 한 곳에 던지는 시대는 비용 측면에서도 곧 끝납니다. 앞으로는 메인 세션 (Claude Opus 4.6 / GPT-5.4)을 두고, reviewer · verifier · docs researcher · browser operator 같은 좁은 역할은 더 작고 빠른 모델 (Claude Haiku 4.5, GPT-5.4 mini, Gemma 4 31B, Qwen3-Coder 30B)로 분리하는 멀티 에이전트 운영이 일반화될 가능성이 높습니다. Anthropic 의 “Building Effective Agents”가 강조한 “필요할 때만 agent, 그 외에는 단순 workflow”라는 원칙도 같은 방향입니다(anthropic.com).

3. 조직 차원의 정책이 개인 프롬프트보다 중요해집니다

“누가 더 좋은 프롬프트를 쓰는가”라는 질문은 점점 의미가 줄어듭니다. 같은 팀이 같은 저장소에서 같은 결과를 일관되게 낼 수 있는가가 더 중요해집니다. 그 일관성을 만드는 것은 개인 감각이 아니라 팀 표준 — 공통 CLAUDE.md / AGENTS.md, 공통 검증 스크립트, 공통 MCP 세트, 공통 위험 명령 차단, 공통 회고 지표 — 입니다. 하네스는 도구 사용법이 아니라 엔지니어링 문화와 운영 표준의 문제입니다.

4. 특히 중요해질 운영 영역 세 가지

5. 한국 조직에 특히 중요한 변수

위의 흐름은 글로벌 공통이지만, 한국 조직에는 추가로 고려해야 할 변수가 몇 개 더 있습니다.

• 데이터 주권과 보안 등급: 공공·금융·국방 도메인은 외부 LLM API 직접 호출이 어려워, 사내 VPC 안에서 돌릴 수 있는 강한 오픈 모델(Gemma 4 31B, Qwen3-Coder 30B 등)과 자체 호스팅 추론 스택의 가치가 더 큽니다. 어느 글로벌 모델이 1등인가보다, 망 분리 환경에서 안정적으로 돌릴 수 있는 모델을 어떻게 운영하는가가 더 실질적인 질문이 됩니다.
• 한국어 코드 리뷰와 사양서 품질: 영어 essay 리뷰는 잘 되지만 한국어 코드 코멘트, 한국어 사양서, 한국어 운영 메시지에서는 모델 차이가 더 큽니다. 이 부분은 외부 벤치마크가 아니라 사내 평가 데이터셋(eval)으로만 측정할 수 있습니다.
• 한국 특화 PII 마스킹: 주민등록번호, 사업자번호, 한글 주소 같은 한국 특화 개인정보 필터링은 대부분의 글로벌 가드레일에 빠져 있어, 사내 hook 또는 사전 필터로 직접 추가해야 안전합니다.
• 요금 환경: 한국 회사 결제 환경에서 OpenAI / Anthropic 구독을 일괄 결제하는 방식이 부서별로 다릅니다. 토큰 비용이 곧 회사 비용이 되는 운영 모델을 미리 정해 두지 않으면, 개인 카드로 시작했다가 회수가 어려운 경우가 자주 생깁니다.

3년 뒤에 무엇이 달라져 있어야 하는가

Dario Amodei 의 “Machines of Loving Grace”(2024년 10월)는 향후 5~10년의 AI 진보가 과학·헬스 케어·개발 생산성에 큰 변화를 줄 가능성을 정리합니다(darioamodei.com). 반면 Sam Altman 의 “Three Observations”(2025년 2월)는 같은 곡선을 더 짧은 시간 단위로 봅니다(blog.samaltman.com). 어느 쪽이 더 맞는지와 무관하게, 조직이 지금부터 3년 동안 갖춰 둬야 하는 능력은 다음 세 가지로 좁혀집니다.

1. 세션 메모리, 검증 명령, MCP 세트, hook 정책을 코드처럼 버전 관리하는 운영 능력
2. 도구 호출과 에이전트 비용을 지표로 보는 관측 인프라
3. 모델이 언제든 교체될 수 있다는 가정 위에서, 모델 종속성을 최소화한 하네스 설계

여기서 더 깊게 보고 싶다면, 두 도구의 공식 자료부터 같은 구조로 정리된 자료 맵을 보십시오 — Claude Code 공식 자료 맵 / Codex 공식 자료 맵. 클라우드 오프로드 planning 의 가장 신선한 사례는 /reference/ultraplan 에 정리돼 있습니다.

주요 자료

• Andrej Karpathy, Software 2.0
• YC: Andrej Karpathy, Software Is Changing (Again)
• Anthropic, Building Effective Agents
• Anthropic Claude Code Overview
• Anthropic Claude Code Memory (CLAUDE.md)
• Anthropic Claude Code Hooks
• Anthropic Claude Code Subagents
• OpenAI Codex Docs
• OpenAI Codex MCP Docs
• OpenAI Codex Hooks Docs
• OpenAI Codex AGENTS.md
• Google Gemma 4 announcement
• Qwen3-Coder official blog
• Context7 installation
• Playwright coding agents