<div id="readability-page-1" class="page"><section itemprop="text">
        
        

<h2 id="0-들어가면서">0. 들어가면서</h2>

<p>지금 개발 업계를 관통하는 키워드는 <code>하네스 엔지니어링(Harness Engineering)</code>이다. 처음 들어보는 사람들도 있겠지만, AI를 활용한 엔지니어링에 관심이 많은 사람들이라면 누구나 들어봤을 거라 생각한다. 나는 AI에 열광적이진 않지만, 소프트웨어 엔지니어 커리어를 지속하려면 AI 기술을 활용한 엔지니어링에 관련된 공부는 계속 이어나가야 한다고 느끼고 있다. 이번 글에선 하네스 엔지니어링이 무엇인지 정리해봤다.</p>

<h2 id="1-what-is-harness-engineering">1. What is Harness Engineering?</h2>

<p><strong>하네스 엔지니어링(Harness Engineering)</strong>은 AI 에이전트가 프로덕션 환경에서 자율적이고 안정적으로 작업을 수행할 수 있도록 에이전트를 둘러싼 제약 조건, 시스템, 그리고 피드백 루프 등 전체 환경을 설계하는 엔지니어링 분야다.</p>

<p><code>하네스 엔지니어링</code>이라는 개념은 야생말(AI 모델)이 경마장에서 날뛰지 않고 인간의 의도대로 빠르고 정확하게 달리게 하려면 고삐나 안장 같은 마구(Harness)가 필요하다는 것에서 유래됐다. 즉, AI 모델의 힘을 단순히 억누르는 것이 아니라, 올바른 방향으로 제어하며 최대한의 능력을 발휘하도록 구조를 씌워주는 것이다.</p>

<p>하네스 엔지니어링이 등장하게 된 배경은 AI 모델의 발전과 이를 활용하는 방식의 진화 과정에서 드러난 명확한 한계들 때문이다. 이 용어는 2026년 2월, 해시코프(HashiCorp)의 <a href="https://mitchellh.com/writing/my-ai-adoption-journey">공동 창업자인 미첼 하시모토(Mitchell Hashimoto)가 AI 코딩 에이전트의 반복되는 실수를 방지하기 위한 시스템 구축 작업을 지칭</a>하며 처음 사용했다. 이후 오픈AI(OpenAI), 엔스로픽(Anthropic), 랭체인(LangChain) 등의 기업들이 동일한 문제의식을 공유하며 빠르게 확산되었다.</p>

<p>하네스 엔지니어링의 핵심 구성 요소는 다음과 같다.</p>

<ul>
  <li>컨텍스트 파일</li>
  <li>기계적 강제 및 피드백 루프</li>
  <li>도구 오케스트레이션 및 안전한 실행 환경</li>
  <li>엔트로피 관리 및 가비지 컬렉션</li>
</ul>

<p>컨텍스트 파일은 <code>AGENTS.md</code>, <code>CLAUDE.md</code>, <code>.cursorrules</code> 등과 같이 에이전트가 작업을 시작할 때 항상 읽어야 하는 프로젝트 규칙, 디렉터리 구조, 코딩 컨벤션을 정의한 지시 파일이다. 에이전트가 기억을 잃어도 새 세션마다 이 파일을 읽어 일관성을 유지한다.</p>

<p>기계적 피드백 루프는 린터(linter), 타입 체커, 테스트, 프리커밋 훅(Pre-commit hook) 등을 통해 에이전트가 규칙을 어기면 자동으로 에러를 발생시키고, 이를 바탕으로 AI가 스스로 코드를 교정하도록 유도하는 자동화된 검증 시스템을 만들자는 취지다. AI 에이전트가 스스로 에러를 교정하기 위해선 에러 메시지와 ‘어떻게 수정해야 하는지’에 대한 구체적인 지침을 에이전트 컨텍스트에 주입해야 한다. AI 에이전트가 추론을 통해 코드를 수정해서 제출하면 규칙에 맞게 다시 검증을 수행한다. 실패하면 다시 에러를 만들고, 에이전트가 다시 코드를 고치는 과정이 기준을 충족할 때까지 자동으로 반복된다. 이때 사람의 개입은 필요 없다.</p>

<p>도구 오케스트레이션은 AI 에이전트가 단순히 코드만 작성하는 것을 넘어서 실제 업무 환경의 다양한 외부 시스템(이슈 트래커, 데이터베이스, 모니터링 시스템 등)과 상호작용할 수 있도록 연결하고 통제하는 기술이다. 에이전트의 접근 범위와 권한 경계를 명확히 설정하고, 에이전트에게 필요한 도구만 선별적으로 쥐어준다. 이를 통해 사고를 칠 수 없도록 안전장치와 한계를 시스템적으로 강제한다. 특정 역할을 맡은 서브 에이전트를 구성했다면 제한된 도구만 부여하여 집중된 실행을 유도하고 권한 남용을 방지한다. 에이전트가 접근할 수 있는 명령어만 명시적으로 허용하고, 에이전트의 코드가 로컬 환경을 망가뜨리지 않도록 격리된 샌드박스(sandbox)를 제공한다. 파일 시스템 및 네트워크 액세스를 제한하는 OS 수준의 격리를 수행해야 한다.</p>

<p>프로젝트는 시간이 지날수록 필연적으로 복잡도가 늘어나고 기술 부채가 쌓인다. 무질서하고 복잡해지는 경향을 <strong>엔트로피(entropy)가 증가한</strong>다고 표현한다. AI 에이전트는 기존의 나쁜 코드 패턴을 그대로 모방하고 복제하는 경향이 있다. 이로 인해 비슷한 중복 코드가 늘어나거나 의도를 적어둔 문서와 다른 코드나 좋지 않은 패턴의 코드들이 빠르게 늘어난다. <strong>가비지-인-가비지-아웃(garbage-in-garbage-out)</strong>인데, 사람이 수동으로 코드를 청소하는 대신 백그라운드에서 주기적으로 돌아가는 청소(리팩토링) 에이전트를 구성한다. 이 에이전트는 문서와 코드의 일관성을 검증하고, 패턴을 위반하거나 순환 의존성을 스캔하거나 사용하지 않는 코드를 찾아내는 등의 작업을 수행해서 프로젝트의 엔트로피를 낮추는 작업을 수행한다.</p>

<p>하네스를 설계하는 목표는 사람의 개입을 완전히 없애는 것은 아니다. AI는 코드를 읽을 수 있지만, 조직의 비즈니스 목표나 경험에서 나오는 감각적으로 느껴지는 코드의 문제 등은 알지 못한다. 사회적 책임도 갖고 있지 않다. 실수했을 때 비용과 대가가 큰 핵심적인 의사 결정 지점에 사람의 판단력을 집중하고, AI가 올바른 방향으로 나아가고 있는지 판단해야 한다.</p>

<p>결론적으로 하네스 엔지니어링의 주요 요소들은 AI 모델의 지능 자체를 높이는 것이 아니라, 명확한 정보(컨텍스트)를 제공하고, 기계적인 제약(피드백 루프)을 가하며, 지속적으로 환경을 청소(가비지 컬렉션)함으로써 에이전트가 안정적으로 일할 수 있는 완벽한 작업 환경을 구축하는 것이 핵심이다.</p>

<h2 id="2-what-did-i-do">2. What did I do?</h2>

<p>위에서 하네스 엔지니어링의 모든 핵심 구성 요소들을 직접 구성해보진 않았지만, 간단한 토이 프로젝트를 통해 하나씩 적용하며 구축해보고 있다. 여러 사람들이 자신의 하네스를 공개하고 있지만, 모든 프로젝트에 범용적으로 활용할 수 있는 완벽한 하네스는 없을 것이라 생각한다. 다른 사람들의 하네스를 사용하는 것보다 프로젝트를 진행해가면서 어떤 상황에 AI 에이전트에게 적절한 제약과 권한을 줄지 나만의 노하우가 필요하다고 생각했다.</p>

<p>처음에는 에이전트의 행동을 마이크로매니징(micromanaging)했다. 각 스텝마다 AI 에이전트의 작업 결과를 리뷰해보니 개발자 스스로가 병목(bottleneck)이 되었다. AI 에이전트가 코드를 작성하고 파일을 수정하는 과정을 사람이 일일이 지켜보고 개입하게 되면, 결국 사람이 작업하는 수준으로 작업 효율이 떨어졌다. 작업 플랜(plan)과 작업 결과를 리뷰하는 데 집중하는 편이 개발 과정에서 AI 에이전트를 효율적으로 사용한다는 느낌을 받았다.</p>

<p>AI의 작업 결과물을 리뷰해보면 제대로 동작하지만, 감각적으로 뭔가 이상함을 느끼는 경우가 종종 있다.</p>

<ul>
  <li>하나의 메소드에 모든 기능을 구현하는 경우 (과도한 책임)</li>
  <li>무엇을 숨기고, 무엇을 노출하는지 잘못된 판단을 하는 경우 (인터페이스 설계)</li>
  <li>불필요한 구현이나 코드가 복잡해 보이는 경우</li>
  <li>모듈 사이의 의존성이 복잡하거나 의존성 사이클이 있는 경우</li>
  <li>적절한 예외 처리가 없거나 메모리 누수, 동시성 문제가 있는 경우</li>
</ul>

<p>좋지 않은 설계는 지금보다는 나중에 변경이 필요하거나 버그나 문제가 생겼을 때 고통을 유발한다. 나중에 고통받기 전에 리뷰하는 시점에 비판적인 시각으로 살펴보는 연습을 의식적으로 하고 있다. 또, AI 에이전트의 결과물에 감각적으로 이상함을 느끼는 이유는 개발자로 일하면서 겪었던 경험들로부터 온다. 리뷰에서 느껴지는 위화감을 실제로 어떤 부분에 문제가 발생할 수 있는지 말로 설명해보려고 하고 있다.</p>

<p>이렇게 비판적인 리뷰가 끝나면 스스로 코드를 변경하거나 AI 에이전트에게 작업을 유도한다. 원하는 패턴대로 작업이 완료되면 작업 내용을 기반으로 프로젝트 컨텍스트를 업데이트한다. 우선 코파일럿(copilot)이나 클로드(claude)에서 기본적으로 제공하는 /init 명령어를 수행한다. 해당 명령어는 현재 프로젝트 상태를 바탕으로 AGENTS.md 혹은 CLAUDE.md 파일을 업데이트해 준다.</p>



<p>개발하면서 AI 에이전트의 컨텍스트를 주기적으로 업데이트해 주기 위한 스킬을 만들어서 사용하고 있다.</p>

<ul>
  <li><a href="https://github.com/Junhyunny/skills/tree/main/sync-conventions">skills/sync-conventions</a></li>
  <li><a href="https://github.com/Junhyunny/skills/tree/main/sync-architecture">skills/sync-architecture</a></li>
</ul>

<p>sync-conventions 스킬은 에이전트가 코드를 양산하거나 인간 개발자가 코드를 수정하면서 필연적으로 발생하는 ‘팀 코딩 규칙의 편차(Convention Drift)’를 감지하고 CONVENTIONS.md 파일을 동기화한다. 프로젝트 전체를 매번 다시 읽는 것이 아니라, 안전하게 변경점만 추적한다.</p>

<p>컨벤션 파일이 이미 존재할 경우 전체 프로젝트를 스캔하지 않는다. <code>git diff</code>로 확인되는 변경된 파일, 최근 에이전트가 제안한 패턴, 사용자가 에디터에서 직접 수정한 코드 조각 등 ‘변경 신호’만을 우선적으로 수집하여 분석 범위를 최소화한다. 수집된 신호를 바탕으로 테스트 작성 방식, 디렉터리 구조, 의존성 주입 방식, 리팩토링 및 중복 제거 기준 등 4가지 영역에서 규칙이 어떻게 달라졌는지 감지한다.</p>

<p>sync-conventions 스킬은 ‘AI의 컨텍스트’와 ‘인간 사용자의 의도’를 비교 추론한다. 만약 에이전트가 짠 코드를 사용자가 직접 다른 구조로 리팩토링했는데, 그 패턴이 여러 파일에서 일관되게 반복된다면 이를 단순한 ‘충돌’이 아니라 <strong>‘사용자의 의도적인 팀 규칙 변경’</strong>으로 간주한다. 사용자의 변경이 합리적이지만 기존 컨벤션과 다를 경우 마음대로 덮어쓰지 않고 사용자에게 먼저 질문(확인)을 거친다. 문서 갱신 시 사용자가 기존에 작성해 둔 커스텀 규칙(## Custom Rules)은 절대 훼손하지 않으며 변경된 항목만 안전하게 부분 갱신한다.</p>

<p>아래 명령어를 통해 설치해서 사용할 수 있다.</p>

<div><pre><code>$ npx skills add junhyunny/skills/sync-conventions
</code></pre></div>

<p>sync-architecture 스킬은 에이전트의 토큰 낭비를 방지하고 경계를 설정하기 위한 ARCHITECTURE.md 파일을 생성한다. AI 에이전트가 작업을 시작할 때 이리저리 파일을 열어보는 ‘탐색, 추측, 되돌아오기’ 과정에서 낭비되는 토큰을 원천적으로 차단하는 것이 주된 목적이다. ARCHITECTURE.md 파일에는 다음과 같은 내용이 포함된다.</p>

<ul>
  <li>구조 파악 (Structure): package.json이나 build.gradle.kts 같은 빌드/패키지 파일을 읽어 기술 스택을 파악하고, 각 영역별 주요 경로와 진입점(Entry point)을 분석한다.</li>
  <li>데이터 흐름 (Flow): 프로세스 간 통신 방식이나 계층(Layer) 간 호출 순서 등 데이터와 요청이 이동하는 단방향 핵심 경로를 파악하여, 에이전트가 엉뚱한 파일을 수정하지 않도록 안내한다.</li>
  <li>경계 설정 (Boundary): 에이전트의 치명적인 실수를 막기 위해 자동 생성 파일(예: api/generated/)이나 외부 관리 UI 컴포넌트 등 ‘절대 수정해서는 안 되는 금지 구역’을 명시하고 그 이유와 대안을 표로 정리한다.</li>
</ul>

<p>아래 명령어를 통해 설치해서 사용할 수 있다.</p>

<div><pre><code>$ npx skills add junhyunny/skills/sync-architecture
</code></pre></div>

<p>위 두 스킬로 생성한 CONVENTIONS.md, ARCHITECTURE.md 파일을 AGENTS.md나 CLAUDE.md 파일에서 다음과 같이 참조한다. AI 에이전트와 함께 일하면서 주기적으로 컨벤션과 아키텍처를 업데이트한다.</p>

<div><pre><code><span>## References</span>
<span>
-</span> 프로젝트 아키텍처 정보: @ARCHITECTURE.md
<span>-</span> 코드 컨벤션 정보: @CONVENTIONS.md
</code></pre></div>

<h2 id="closing">CLOSING</h2>

<p>다음에는 AI 에이전트 개발을 위한 안전한 개발 환경인 샌드박스 구축 방법이나 가비지 컬렉션 서브 에이전트나 스킬을 만드는 방법을 토이 프로젝트에 적용해보고 정리해 볼 생각이다.</p>

<h4 id="reference">REFERENCE</h4>

<ul>
  <li><a href="https://daleseo.com/harness-engineering/">https://daleseo.com/harness-engineering/</a></li>
  <li><a href="https://madplay.github.io/post/harness-engineering">https://madplay.github.io/post/harness-engineering</a></li>
  <li><a href="https://mitchellh.com/writing/my-ai-adoption-journey">https://mitchellh.com/writing/my-ai-adoption-journey</a></li>
  <li><a href="https://www.youtube.com/watch?v=DrekqeDlO1w">https://www.youtube.com/watch?v=DrekqeDlO1w</a></li>
  <li><a href="https://martinfowler.com/articles/harness-engineering.html">https://martinfowler.com/articles/harness-engineering.html</a></li>
</ul>

        
      </section></div>

Junhyunny's Devlogs

0. 들어가면서
지금 개발 업계를 관통하는 키워드는 하네스 엔지니어링(Harness Engineering)이다. 처음 들어보는 사람들도 있겠지만, AI를 활용한 엔지니어링에 관심이 많은 사람들이라면 누구나 들어봤을 거라 생각한다. 나는 AI에 열광적이진 않지만, 소프트웨어 엔지니어 커리어를 지속하려면 AI 기술을 활용한 엔지니어링에 관련된 공부는 계속 이어나가야 한다고 느끼고 있다. 이번 글에선 하네스 엔지니어링이 무엇인지 정리해봤다.
1. What is Harness Engineering?
하네스 엔지니어링(Harness Engineering)은 AI 에이전트가 프로덕션 환경에서 자율적이고 안정적으로 작업을 수행할 수 있도록 에이전트를 둘러싼 제약 조건, 시스템, 그리고 피드백 루프 등 전체 환경을 설계하는 엔지니어링 분야다.
하네스 엔지니어링이라는 개념은 야생말(AI 모델)이 경마장에서 날뛰지 않고 인간의 의도대로 빠르고 정확하게 달리게 하려면 고삐나 안장 같은 마구(Harness)가 필요하다는 것에서 유래됐다. 즉, AI 모델의 힘을 단순히 억누르는 것이 아니라, 올바른 방향으로 제어하며 최대한의 능력을 발휘하도록 구조를 씌워주는 것이다.
하네스 엔지니어링이 등장하게 된 배경은 AI 모델의 발전과 이를 활용하는 방식의 진화 과정에서 드러난 명확한 한계들 때문이다. 이 용어는 2026년 2월, 해시코프(HashiCorp)의 공동 창업자인 미첼 하시모토(Mitchell Hashimoto)가 AI 코딩 에이전트의 반복되는 실수를 방지하기 위한 시스템 구축 작업을 지칭하며 처음 사용했다. 이후 오픈AI(OpenAI), 엔스로픽(Anthropic), 랭체인(LangChain) 등의 기업들이 동일한 문제의식을 공유하며 빠르게 확산되었다.
하네스 엔지니어링의 핵심 구성 요소는 다음과 같다.
컨텍스트 파일
기계적 강제 및 피드백 루프
도구 오케스트레이션 및 안전한 실행 환경
엔트로피 관리 및 가비지 컬렉션
컨텍스트 파일은 AGENTS.md, CLAUDE.md, .cursorrules 등과 같이 에이전트가 작업을 시작할 때 항상 읽어야 하는 프로젝트 규칙, 디렉터리 구조, 코딩 컨벤션을 정의한 지시 파일이다. 에이전트가 기억을 잃어도 새 세션마다 이 파일을 읽어 일관성을 유지한다.
기계적 피드백 루프는 린터(linter), 타입 체커, 테스트, 프리커밋 훅(Pre-commit hook) 등을 통해 에이전트가 규칙을 어기면 자동으로 에러를 발생시키고, 이를 바탕으로 AI가 스스로 코드를 교정하도록 유도하는 자동화된 검증 시스템을 만들자는 취지다. AI 에이전트가 스스로 에러를 교정하기 위해선 에러 메시지와 ‘어떻게 수정해야 하는지’에 대한 구체적인 지침을 에이전트 컨텍스트에 주입해야 한다. AI 에이전트가 추론을 통해 코드를 수정해서 제출하면 규칙에 맞게 다시 검증을 수행한다. 실패하면 다시 에러를 만들고, 에이전트가 다시 코드를 고치는 과정이 기준을 충족할 때까지 자동으로 반복된다. 이때 사람의 개입은 필요 없다.
도구 오케스트레이션은 AI 에이전트가 단순히 코드만 작성하는 것을 넘어서 실제 업무 환경의 다양한 외부 시스템(이슈 트래커, 데이터베이스, 모니터링 시스템 등)과 상호작용할 수 있도록 연결하고 통제하는 기술이다. 에이전트의 접근 범위와 권한 경계를 명확히 설정하고, 에이전트에게 필요한 도구만 선별적으로 쥐어준다. 이를 통해 사고를 칠 수 없도록 안전장치와 한계를 시스템적으로 강제한다. 특정 역할을 맡은 서브 에이전트를 구성했다면 제한된 도구만 부여하여 집중된 실행을 유도하고 권한 남용을 방지한다. 에이전트가 접근할 수 있는 명령어만 명시적으로 허용하고, 에이전트의 코드가 로컬 환경을 망가뜨리지 않도록 격리된 샌드박스(sandbox)를 제공한다. 파일 시스템 및 네트워크 액세스를 제한하는 OS 수준의 격리를 수행해야 한다.
프로젝트는 시간이 지날수록 필연적으로 복잡도가 늘어나고 기술 부채가 쌓인다. 무질서하고 복잡해지는 경향을 엔트로피(entropy)가 증가한다고 표현한다. AI 에이전트는 기존의 나쁜 코드 패턴을 그대로 모방하고 복제하는 경향이 있다. 이로 인해 비슷한 중복 코드가 늘어나거나 의도를 적어둔 문서와 다른 코드나 좋지 않은 패턴의 코드들이 빠르게 늘어난다. 가비지-인-가비지-아웃(garbage-in-garbage-out)인데, 사람이 수동으로 코드를 청소하는 대신 백그라운드에서 주기적으로 돌아가는 청소(리팩토링) 에이전트를 구성한다. 이 에이전트는 문서와 코드의 일관성을 검증하고, 패턴을 위반하거나 순환 의존성을 스캔하거나 사용하지 않는 코드를 찾아내는 등의 작업을 수행해서 프로젝트의 엔트로피를 낮추는 작업을 수행한다.
하네스를 설계하는 목표는 사람의 개입을 완전히 없애는 것은 아니다. AI는 코드를 읽을 수 있지만, 조직의 비즈니스 목표나 경험에서 나오는 감각적으로 느껴지는 코드의 문제 등은 알지 못한다. 사회적 책임도 갖고 있지 않다. 실수했을 때 비용과 대가가 큰 핵심적인 의사 결정 지점에 사람의 판단력을 집중하고, AI가 올바른 방향으로 나아가고 있는지 판단해야 한다.
결론적으로 하네스 엔지니어링의 주요 요소들은 AI 모델의 지능 자체를 높이는 것이 아니라, 명확한 정보(컨텍스트)를 제공하고, 기계적인 제약(피드백 루프)을 가하며, 지속적으로 환경을 청소(가비지 컬렉션)함으로써 에이전트가 안정적으로 일할 수 있는 완벽한 작업 환경을 구축하는 것이 핵심이다.
2. What did I do?
위에서 하네스 엔지니어링의 모든 핵심 구성 요소들을 직접 구성해보진 않았지만, 간단한 토이 프로젝트를 통해 하나씩 적용하며 구축해보고 있다. 여러 사람들이 자신의 하네스를 공개하고 있지만, 모든 프로젝트에 범용적으로 활용할 수 있는 완벽한 하네스는 없을 것이라 생각한다. 다른 사람들의 하네스를 사용하는 것보다 프로젝트를 진행해가면서 어떤 상황에 AI 에이전트에게 적절한 제약과 권한을 줄지 나만의 노하우가 필요하다고 생각했다.
처음에는 에이전트의 행동을 마이크로매니징(micromanaging)했다. 각 스텝마다 AI 에이전트의 작업 결과를 리뷰해보니 개발자 스스로가 병목(bottleneck)이 되었다. AI 에이전트가 코드를 작성하고 파일을 수정하는 과정을 사람이 일일이 지켜보고 개입하게 되면, 결국 사람이 작업하는 수준으로 작업 효율이 떨어졌다. 작업 플랜(plan)과 작업 결과를 리뷰하는 데 집중하는 편이 개발 과정에서 AI 에이전트를 효율적으로 사용한다는 느낌을 받았다.
AI의 작업 결과물을 리뷰해보면 제대로 동작하지만, 감각적으로 뭔가 이상함을 느끼는 경우가 종종 있다.
하나의 메소드에 모든 기능을 구현하는 경우 (과도한 책임)
무엇을 숨기고, 무엇을 노출하는지 잘못된 판단을 하는 경우 (인터페이스 설계)
불필요한 구현이나 코드가 복잡해 보이는 경우
모듈 사이의 의존성이 복잡하거나 의존성 사이클이 있는 경우
적절한 예외 처리가 없거나 메모리 누수, 동시성 문제가 있는 경우
좋지 않은 설계는 지금보다는 나중에 변경이 필요하거나 버그나 문제가 생겼을 때 고통을 유발한다. 나중에 고통받기 전에 리뷰하는 시점에 비판적인 시각으로 살펴보는 연습을 의식적으로 하고 있다. 또, AI 에이전트의 결과물에 감각적으로 이상함을 느끼는 이유는 개발자로 일하면서 겪었던 경험들로부터 온다. 리뷰에서 느껴지는 위화감을 실제로 어떤 부분에 문제가 발생할 수 있는지 말로 설명해보려고 하고 있다.
이렇게 비판적인 리뷰가 끝나면 스스로 코드를 변경하거나 AI 에이전트에게 작업을 유도한다. 원하는 패턴대로 작업이 완료되면 작업 내용을 기반으로 프로젝트 컨텍스트를 업데이트한다. 우선 코파일럿(copilot)이나 클로드(claude)에서 기본적으로 제공하는 /init 명령어를 수행한다. 해당 명령어는 현재 프로젝트 상태를 바탕으로 AGENTS.md 혹은 CLAUDE.md 파일을 업데이트해 준다.
/init
개발하면서 AI 에이전트의 컨텍스트를 주기적으로 업데이트해 주기 위한 스킬을 만들어서 사용하고 있다.
skills/sync-conventions
skills/sync-architecture
sync-conventions 스킬은 에이전트가 코드를 양산하거나 인간 개발자가 코드를 수정하면서 필연적으로 발생하는 ‘팀 코딩 규칙의 편차(Convention Drift)’를 감지하고 CONVENTIONS.md 파일을 동기화한다. 프로젝트 전체를 매번 다시 읽는 것이 아니라, 안전하게 변경점만 추적한다.
컨벤션 파일이 이미 존재할 경우 전체 프로젝트를 스캔하지 않는다. git diff로 확인되는 변경된 파일, 최근 에이전트가 제안한 패턴, 사용자가 에디터에서 직접 수정한 코드 조각 등 ‘변경 신호’만을 우선적으로 수집하여 분석 범위를 최소화한다. 수집된 신호를 바탕으로 테스트 작성 방식, 디렉터리 구조, 의존성 주입 방식, 리팩토링 및 중복 제거 기준 등 4가지 영역에서 규칙이 어떻게 달라졌는지 감지한다.
sync-conventions 스킬은 ‘AI의 컨텍스트’와 ‘인간 사용자의 의도’를 비교 추론한다. 만약 에이전트가 짠 코드를 사용자가 직접 다른 구조로 리팩토링했는데, 그 패턴이 여러 파일에서 일관되게 반복된다면 이를 단순한 ‘충돌’이 아니라 ‘사용자의 의도적인 팀 규칙 변경’으로 간주한다. 사용자의 변경이 합리적이지만 기존 컨벤션과 다를 경우 마음대로 덮어쓰지 않고 사용자에게 먼저 질문(확인)을 거친다. 문서 갱신 시 사용자가 기존에 작성해 둔 커스텀 규칙(## Custom Rules)은 절대 훼손하지 않으며 변경된 항목만 안전하게 부분 갱신한다.
아래 명령어를 통해 설치해서 사용할 수 있다.
$ npx skills add junhyunny/skills/sync-conventions
sync-architecture 스킬은 에이전트의 토큰 낭비를 방지하고 경계를 설정하기 위한 ARCHITECTURE.md 파일을 생성한다. AI 에이전트가 작업을 시작할 때 이리저리 파일을 열어보는 ‘탐색, 추측, 되돌아오기’ 과정에서 낭비되는 토큰을 원천적으로 차단하는 것이 주된 목적이다. ARCHITECTURE.md 파일에는 다음과 같은 내용이 포함된다.
구조 파악 (Structure): package.json이나 build.gradle.kts 같은 빌드/패키지 파일을 읽어 기술 스택을 파악하고, 각 영역별 주요 경로와 진입점(Entry point)을 분석한다.
데이터 흐름 (Flow): 프로세스 간 통신 방식이나 계층(Layer) 간 호출 순서 등 데이터와 요청이 이동하는 단방향 핵심 경로를 파악하여, 에이전트가 엉뚱한 파일을 수정하지 않도록 안내한다.
경계 설정 (Boundary): 에이전트의 치명적인 실수를 막기 위해 자동 생성 파일(예: api/generated/)이나 외부 관리 UI 컴포넌트 등 ‘절대 수정해서는 안 되는 금지 구역’을 명시하고 그 이유와 대안을 표로 정리한다.
아래 명령어를 통해 설치해서 사용할 수 있다.
$ npx skills add junhyunny/skills/sync-architecture
위 두 스킬로 생성한 CONVENTIONS.md, ARCHITECTURE.md 파일을 AGENTS.md나 CLAUDE.md 파일에서 다음과 같이 참조한다. AI 에이전트와 함께 일하면서 주기적으로 컨벤션과 아키텍처를 업데이트한다.
## References
- 프로젝트 아키텍처 정보: @ARCHITECTURE.md
- 코드 컨벤션 정보: @CONVENTIONS.md
CLOSING
다음에는 AI 에이전트 개발을 위한 안전한 개발 환경인 샌드박스 구축 방법이나 가비지 컬렉션 서브 에이전트나 스킬을 만드는 방법을 토이 프로젝트에 적용해보고 정리해 볼 생각이다.
REFERENCE
https://daleseo.com/harness-engineering/
https://madplay.github.io/post/harness-engineering
https://mitchellh.com/writing/my-ai-adoption-journey
https://www.youtube.com/watch?v=DrekqeDlO1w
https://martinfowler.com/articles/harness-engineering.html

하네스 엔지니어링(Harness Engineering)

댓글