"하네스가 전부다 (3/4) — ACI와 에이전트-퍼스트 엔지니어링이 중요한 이유"

-

에이전트를 더 잘 만들고 싶을 때 우리는 오랫동안 프롬프트나 모델 스펙부터 봤다. 하지만 실무는 점점 다른 방향으로 이동하고 있다. 더 중요한 질문은 "모델이 얼마나 똑똑한가"가 아니라 "이 에이전트가 어떤 작업대에서 일하는가"다. ACI, 즉 Agent-Computer Interface는 이 전환을 설명하는 핵심 개념이다. 하네스는 보조 장치가 아니라, 에이전트가 세상을 경험하는 방식 자체다.

핵심 요약

  • ACI는 에이전트를 위한 작업 인터페이스다. 사람용 UI를 그대로 주는 것이 아니라, 에이전트가 판단하고 행동하기 쉬운 작업 표면을 설계하는 개념이다.
  • 에이전트-퍼스트 엔지니어링은 모델 하나를 바꾸는 일보다, 파일 구조, 도구 표면, 피드백 루프, handoff artifact, 평가 경계를 먼저 다듬는 접근에 가깝다.
  • 같은 모델이라도 어떤 인터페이스와 하네스를 주느냐에 따라 성능 차이가 크게 난다. 이것이 "하네스가 전부다"는 말의 실무적 의미다.
  • 좋은 ACI는 더 많은 기능을 주는 것이 아니라, 선택 비용을 줄이고 실패 반경을 줄이는 구조를 준다.
  • D3의 초점은 일반론적 프롬프트 팁이 아니라, ACI와 agent-first engineering이 왜 전략 레벨에서 중요한가다.

1. 왜 이제는 프롬프트보다 작업대가 더 중요한가

프롬프트 엔지니어링이 중요하지 않다는 뜻은 아니다. 다만 에이전트가 파일을 읽고, 도구를 호출하고, 장시간 작업을 이어 가는 순간부터 문제의 중심이 바뀐다.

이때 더 중요한 질문은 보통 이런 것들이다.

  • 필요한 정보를 쉽게 찾을 수 있는가
  • 어떤 행동이 허용되고 어떤 행동이 금지되는가
  • 실패를 빨리 감지할 수 있는가
  • 다음 세션이 어디서 다시 시작해야 하는가
  • 에이전트가 사용할 도구가 작고 분명한가

이 질문들은 전부 프롬프트 문장 하나로 해결되지 않는다. 전부 작업 환경 설계, 즉 하네스 문제다.

그래서 하네스 엔지니어링 관점에서는 흐름이 이렇게 이동한다.

  1. 좋은 프롬프트를 쓴다
  2. 좋은 컨텍스트 구조를 만든다
  3. 좋은 작업 환경과 피드백 루프를 만든다

ACI는 바로 3번의 언어다.

2. ACI는 에이전트용 작업 인터페이스라는 뜻이다

사람에게 좋은 인터페이스가 에이전트에게도 좋은 것은 아니다. 사람은 화면을 훑고, 암묵적 문맥을 추론하고, 복잡한 레이아웃을 감으로 이해할 수 있다. 에이전트는 그렇지 않다.

에이전트에게 더 중요한 것은 대체로 아래와 같다.

  • 명확한 이름
  • 좁은 선택지
  • 구조화된 입력
  • 짧고 출처가 있는 출력
  • 다음 행동을 결정하기 쉬운 상태 표현

즉 ACI는 GUI 예쁘게 만들기의 문제가 아니다. 에이전트가 컴퓨터와 상호작용할 때 어떤 표면을 보게 할 것인가의 문제다.

예를 들면:

  • 거대한 자유형 파일시스템보다, 목적별 디렉터리와 읽기 우선순위가 보이는 구조
  • 만능 도구 하나보다, 검색·읽기·수정·실행이 분리된 도구 표면
  • 장문의 작업 설명보다, 짧은 규칙과 외부 artifact로 나뉜 구조
  • 기억에 의존한 이어쓰기보다, handoff 문서와 progress file이 있는 구조

이 모든 것이 ACI다.

3. "하네스가 전부다"는 말은 왜 과장이 아닌가

처음 들으면 과장처럼 보일 수 있다. 모델도 중요하고, 데이터도 중요하고, 프롬프트도 중요하기 때문이다. 하지만 작업형 에이전트에서는 하네스가 나머지 요소의 체감 가치를 크게 좌우한다.

같은 모델이라도 아래 차이로 결과가 바뀐다.

  • 도구 이름이 선명한가 모호한가
  • 수정 가능한 범위가 명확한가 무한한가
  • 결과 검증이 있는가 없는가
  • 다음 세션을 위한 인계 문서가 있는가 없는가
  • 실패 사례가 평가셋에 편입되는가 사라지는가

즉 하네스는 모델을 보조하는 장식이 아니다. 모델이 실제로 어떤 세계를 보고 어떤 행동을 선택할 수 있는지를 규정한다.

이 의미에서 "하네스가 전부다"는 말은 "모델은 중요하지 않다"가 아니라, 모델이 일하는 실제 환경이 결과를 결정한다는 뜻에 가깝다.

4. 에이전트-퍼스트 엔지니어링은 사람 중심 구조를 다시 묻는다

기존 소프트웨어 구조는 대개 사람 개발자와 사람 운영자를 기준으로 최적화돼 있다. 파일명도, 스크립트도, 문서도 사람이 알아보면 된다는 전제가 많다. 하지만 에이전트를 작업 주체로 넣기 시작하면 이 전제가 흔들린다.

예를 들어 agent-first engineering은 이런 질문을 던진다.

  • 이 디렉터리 구조는 에이전트가 목적을 추론하기 쉬운가
  • 이 문서는 항상 읽혀야 하는 규칙인가, 필요할 때만 불러와야 하는 절차인가
  • 이 명령은 만능인가, 아니면 역할이 좁은가
  • 이 로그와 결과는 다음 행동 판단에 바로 쓰기 쉬운가
  • 실패했을 때 사람이 아니라 에이전트도 복구 경로를 찾을 수 있는가

이 질문들은 단순한 "AI 적용"이 아니라, 시스템을 에이전트도 일할 수 있는 작업장으로 재설계하는 일에 가깝다.

5. 좋은 ACI는 더 많은 능력이 아니라 더 좋은 선택 구조를 준다

ACI를 잘못 이해하면 "에이전트에게 더 많은 권한과 더 많은 도구를 주자"로 흐르기 쉽다. 하지만 실제로는 반대인 경우가 많다.

좋은 ACI는 보통 아래 특성을 가진다.

특성 의미
명확한 표지판 무엇을 먼저 읽고 어디서 작업할지 분명하다
좁은 도구 표면 비슷한 도구가 중복되지 않고 위험도가 분리된다
구조화된 상태 progress, handoff, task artifact가 다음 행동을 돕는다
빠른 피드백 테스트, lint, rule check가 실패를 빨리 드러낸다
짧은 경로 목표를 달성하기 위해 거쳐야 할 판단 단계가 줄어든다

즉 좋은 ACI는 에이전트를 "더 자유롭게" 만들기보다, 덜 헷갈리게 만든다.

6. 우리 저장소 같은 환경에서는 ACI가 특히 중요하다

콘텐츠, 문서, 스크립트, 발행 경계가 함께 있는 저장소에서는 사람도 헷갈리기 쉽다. 에이전트라면 더 그렇다. 그래서 agent-first 관점에서는 구조가 곧 품질이다.

예를 들어 아래 같은 요소는 전부 ACI의 일부다.

  • AGENTS.md 또는 CLAUDE.md의 read-first 규칙
  • tasks/plan.md, tasks/handoffs/, tasks/sessions/ 같은 handoff artifact
  • docs/memory-map.md처럼 기억 경로를 알려 주는 지도
  • sources/, drafts/, docs/, scripts/의 역할 분리
  • 발행 금지, credential 금지 같은 hard boundary

이 구조가 없으면 에이전트는 매번 "어디서 시작해야 하지?"부터 다시 고민한다. 구조가 있으면 에이전트는 판단을 목표에 더 가까운 곳에 쓸 수 있다.

7. ACI는 장시간 에이전트 시대에 더 중요해진다

짧은 단발성 질의에서는 인터페이스 차이가 크게 안 보일 수도 있다. 하지만 장시간 작업에서는 ACI의 질이 곧 생산성 차이가 된다.

왜냐하면 긴 작업은 항상 아래 문제를 부르기 때문이다.

  • 컨텍스트 창 고갈
  • 세션 단절
  • 중간 결과 유실
  • 규칙 누락
  • 범위 이탈

이 문제는 "더 긴 프롬프트"로 잘 안 풀린다. 대신 아래가 풀어 준다.

  • progress artifact
  • 명확한 ownership
  • 좁은 수정 범위
  • 단계별 검증
  • 인계 문서

즉 장시간 에이전트 운영은 ACI의 중요성을 확대하는 환경이다.

8. ACI를 설계할 때 가장 흔한 실패

사람 기준으로만 구조를 만든다

파일명, 디렉터리, 명령이 사람에게만 익숙하고 에이전트에게는 모호할 수 있다.

만능 도구와 만능 규칙을 선호한다

하나의 거대한 instruction 파일, 하나의 만능 스크립트, 하나의 범용 권한은 선택 비용을 올린다.

상태를 대화 안에만 남긴다

세션이 바뀌면 작업이 끊기고, 재시작 비용이 커진다.

실패를 늦게 발견한다

검증이 뒤에 몰리면 에이전트는 이미 멀리 잘못 가 있다.

9. 실무 적용: agent-first engineering은 어디서 시작해야 하나

처음부터 모든 것을 다시 설계할 필요는 없다. 보통은 아래 순서가 현실적이다.

  1. 항상 읽혀야 하는 규칙과 필요할 때만 읽을 절차를 분리한다.
  2. 디렉터리 역할과 수정 범위를 명확히 적는다.
  3. 도구를 검색·읽기·수정·실행으로 나눠 위험도를 분리한다.
  4. 다음 세션이 이어받을 artifact를 만든다.
  5. 실패를 빨리 드러내는 검증을 앞단에 둔다.

이 다섯 가지만 해도 "에이전트가 일을 잘 못한다"는 불만 중 상당수가 사실은 ACI 문제였다는 것이 보이기 시작한다.

10. 결론: 에이전트 시대의 경쟁력은 모델 사용법보다 작업장 설계에 가깝다

하네스 엔지니어링이 전략 주제가 되는 이유는 단순하다. 이제 많은 팀이 비슷한 모델에 접근할 수 있기 때문이다. 그 상태에서 차이를 만드는 것은 모델 호출 권한 자체보다, 그 모델이 어떤 작업장 안에서 어떤 표면을 통해 세상을 보느냐다.

ACI와 agent-first engineering은 바로 그 차이를 설명한다.

  • 프롬프트를 길게 쓰는 팀보다
  • 작업 환경을 선명하게 설계한 팀이
  • 장기적으로 더 안정적인 에이전트를 만들 가능성이 크다

그래서 D3의 결론은 이것이다.

에이전트를 더 똑똑하게 만들고 싶다면, 먼저 그 에이전트가 일하는 작업대를 더 똑똑하게 만들어야 한다.

다음 D4에서는 이 관점을 실제 사례에 대입해, OpenAI, Anthropic, Vercel, GitHub 같은 팀들이 어떤 하네스 패턴을 택했는지 본다.

참고 자료

  • docs/blog_series_하네스엔지니어링_총괄_design.md
  • sources/260518_하네스엔지니어링_15장_블로그활용노트.md
  • drafts/blog/260519_하네스시리즈A03_컨텍스트설계와지시파일_블로그.md
  • drafts/blog/260519_하네스시리즈A04_MCP와도구엔지니어링_블로그.md
  • drafts/blog/260519_하네스시리즈C02_장시간에이전트운영_블로그.md
  • WikiDocs 하네스 엔지니어링 백과사전 13장, 15장 활용 메모

이 글은 패턴·전략·사례 시리즈의 3/4 편입니다. 후속 읽기: 실전 사례로 배우는 하네스 엔지니어링.

시리즈 전체 안내: 하네스 엔지니어링 시리즈 안내

댓글

댓글 쓰기

이 블로그의 인기 게시물

"LLM 핵심 학습 (1/6) — 기본: 토큰화·임베딩·어텐션·위치 인코딩"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/6 파인튜닝 → 트랜스포머 한 블록의 데이터 흐름을 문자열 → 토큰 → 임베딩 → 어텐션 → 출력 표현 까지 손으로 풀어 본다. 이번 편이 끝나면 "왜 \(\sqrt{d_k}\)로 나누는가", "RoPE는 무엇을 회전시키는가", "한국어가 영어보다 토큰이 많은 까닭은 무엇인가"가 한 줄로 설명될 수 있다. 0. 학습 목표 이 편을 마치면 다음을 직접 할 수 있다. BPE 토크나이저 가 어휘를 어떻게 학습하고 새 문자열을 어떻게 자르는지 종이 위에서 시뮬레이션한다. 임베딩 행렬 의 모양과 초기화, weight tying의 의미를 한 줄로 설명한다. Scaled Dot-Product Attention 의 식을 차원 단위로 추적하고 PyTorch 30줄로 재현한다. Multi-Head Attention 이 한 헤드와 비교해 무엇이 다른지, 헤드 수가 늘면 어디가 비싸지는지 답한다. Sinusoidal·RoPE·ALiBi 세 위치 인코딩의 식과 외삽 성질을 구분한다. 컨텍스트 확장이 왜 \(O(N^2)\)인지, "Lost in the Middle"이 왜 발생하는지 설명한다. 1. 핵심 요약 트랜스포머의 입력은 문자열 이 아니라 정수 ID 시퀀스 다. 토크나이저가 문자열 → ID로 자른다. 임베딩은 정수 ID를 \(d\)차원 벡터로 lookup하는 학습 가능한 테이블이다. Self-Attention은 \(\text{softmax}(QK^\top / \sqrt{d_k}) V\) 한 줄이 핵심이고, 멀티헤드는 같은 연산을 여러 부분 공간에서 병렬화한 것이다. 위치 정보는 임베딩에 직접 더하거나(Sinusoidal), Q·K에 회전을 가하거나(RoPE), 어텐션 스코어에 거리 패널티를 더해서(ALiBi) 주입한다. 컨텍스트 길이 \(N\)에 대해 표준 어텐션은 \(O(N^2)\) 비용을 갖고, 긴 컨텍스트에서는 중간 위...
Read more »

"LLM 핵심 학습 (2/6) — 파인튜닝: LoRA·QLoRA·증류·Adapter"

-
이미지
← 1/6 기본 📚 시리즈 목차 3/6 디코딩과 생성 → 사전학습된 LLM을 내 데이터 에 적응시키는 방법을 비용·메모리·일반화 관점에서 정리한다. Full FT의 한계 → Adapter → LoRA → QLoRA → Distillation 순으로 같은 그림을 점점 확대해 본다. 0. 학습 목표 Full fine-tuning의 메모리 병목을 옵티마이저 상태·그래디언트·가중치·활성화 의 4분할로 설명한다. Adapter(Houlsby 2019)와 LoRA(Hu 2021)의 식 차이를 한 줄로 적는다. LoRA의 \(A, B\) 행렬이 왜 저랭크 이고, rank \(r\) 선택이 무엇을 결정하는지 답한다. QLoRA(Dettmers 2023)의 NF4·double-quant·paged optimizer를 분리해서 설명한다. Catastrophic Forgetting을 분포 시프트 관점에서 정의하고 완화 기법을 두 개 이상 든다. Hinton 2015의 Knowledge Distillation 식을 손으로 유도한다. 1. 핵심 요약 Full FT는 메모리/디스크/시간 모두 비싸다. 7B 모델 full FT는 V100 8장 + A100 1장으로도 큰 부담이다. PEFT(파라미터 효율 파인튜닝) 일가족은 극히 일부 파라미터만 학습 해 같은 효과를 얻는다. LoRA: \(\Delta W = BA\) (rank \(r \ll \min(d_{\text{in}}, d_{\text{out}})\))로 가중치 업데이트를 저랭크 분해. QLoRA: 베이스 모델을 4-bit(NF4)로 양자화한 채 LoRA만 풀-정밀(BF16)으로 학습. Catastrophic Forgetting: 새 분포에 적응하느라 이전 능력이 무너지는 현상. PEFT 자체가 부분 완화책. Distillation: 큰 교사 모델의 soft target 을 학습 신호로 써서 작은 학생 모델 을 만든다. 2. 직관: 왜 사전학습만으로는 부족한가 사전학습은 일반...
Read more »

"ML 기초 학습 (1/9) — 머신러닝과 sklearn: 학습의 좌표계"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/9 이웃 알고리즘 → 이 시리즈는 신경망과 로컬 LLM으로 가기 전에 손에 익혀 둬야 할 머신러닝 기초 9편이다. 1편은 모든 ML 코드가 공유하는 공통 문법 을 잡는 데 쓴다. sklearn은 그 문법을 가장 일관되게 보여주는 도구다. 이번 편이 끝나면 어떤 모델을 만나도 fit → predict → score → 평가 흐름이 같다는 것이 손에 잡힌다. 0. 학습 목표 이 편을 마치면 다음을 할 수 있어야 한다. 지도학습·비지도학습·강화학습을 한 문장씩 구분해 설명한다. sklearn의 estimator 인터페이스 ( fit , predict , score , transform )를 코드 한 화면 안에서 쓸 수 있다. train/validation/test 분할을 왜 하는지, 어디서 데이터 누수가 생기는지 식과 그림으로 설명한다. 분류·회귀의 핵심 평가 지표(accuracy, precision, recall, F1, MSE, R²)를 정의에서 직접 계산할 수 있다. k-fold 교차검증 을 코드 한 줄로 돌리고, 결과의 평균과 표준편차를 함께 보고할 수 있다. Pipeline 으로 전처리와 모델을 묶어 데이터 누수를 구조적으로 막는 방법을 설명한다. 1. 핵심 요약 머신러닝은 데이터에서 함수 \(f: X \to Y\)를 찾는 작업 이다. 어떤 모델이든 이 본질은 같다. sklearn은 모든 모델을 같은 인터페이스( fit , predict , score )로 통일해, 모델을 바꿀 때 한 줄만 바꾸면 되게 한다. train/val/test 세 분할이 표준이다. 검증으로 하이퍼파라미터를 고르고, 테스트는 마지막에 한 번만 본다. 데이터 누수 (test 정보가 train에 새는 현상)는 ML 입문자가 가장 자주 만드는 실수이며, Pipeline + cross_val_score 조합으로 구조적으로 막을 수 있다. 평가 지표는 문제 유형 (분류/회귀) 과 클래스 불균형...
Read more »