AI 하네스
AI Harness
1. AI 하네스란?
먼저 AI 하네스가 뭔지부터 설명하겠습니다.
AI 하네스는 쉽게 말하면 AI가 우리가 원하는 방향으로 움직이도록 잡아주는 장치나 규칙이라고 생각하면 됩니다.
요즘 AI는 단순히 코드를 작성하는 것뿐만 아니라 파일을 읽고 수정하거나, 터미널에서 명령어를 실행하고 테스트까지 할 수 있습니다.
그만큼 AI가 할 수 있는 일이 많아졌는데, 반대로 잘못 행동했을 때 문제가 생길 가능성도 커졌습니다.
그래서 AI가 무엇을 할 수 있는지, 무엇을 하면 안 되는지, 어디까지 접근할 수 있는지를 정해주는 게 필요합니다.
그 역할을 하는 게 AI 하네스입니다.
그럼 실제 개발 환경에서 왜 필요한지 보겠습니다.
2. AI Harness가 필요한 이유
저희도 개발하면서 Claude, Codex, Gemini 같은 AI 도구를 사용하고 있습니다.
특히 AI를 개발 환경에 연결하면 파일을 수정하거나 터미널 명령어를 실행하는 등 실제로 개발 환경에 영향을 줄 수 있습니다.
그래서 AI에게 모든 권한을 주면 문제가 생길 수 있습니다.
중요한 파일을 수정하거나 삭제할 수도 있고, 민감한 정보에 접근할 수도 있습니다.
그래서 AI에게 단순히 능력을 주는 것에서 끝나는 게 아니라,
어떤 능력을 줄 것인지, 그리고 그 능력을 어디까지 사용할 수 있게 할 것인지를 같이 정해야 합니다.
이걸 관리하기 위한 개념이 AI Harness입니다.
3. AI Harness의 주요 개념
AI Harness를 이해할 때 크게 다섯 가지를 보면 됩니다.
Tool, Context, Guardrail, 권한과 데이터 관리, Monitoring & Feedback입니다.
간단하게 보면
Tool은 AI가 무엇을 할 수 있는가
Context는 AI에게 무엇을 알려줄 것인가
Guardrail은 AI가 무엇을 하면 안 되는가
권한과 데이터 관리는 AI가 어디까지 접근할 수 있는가
Monitoring & Feedback은 AI가 무엇을 했고 어떻게 개선할 것인가
입니다.
이제 하나씩 보겠습니다.
3-1. Tool
먼저 Tool입니다.
Tool은 쉽게 말해서 AI에게 어떤 능력을 줄 것인가입니다.
LLM 자체는 코드를 생성할 수 있지만, 컴퓨터의 파일을 직접 수정하거나 터미널 명령어를 실행할 수 있는 건 아닙니다.
이런 작업을 하기 위해 Tool을 사용합니다.
예를 들어 파일 읽기, 파일 수정, Terminal, Git 같은 것들이 있습니다.
Tool을 많이 제공할수록 AI가 할 수 있는 일도 많아집니다.
하지만 그만큼 AI가 잘못 행동했을 때 영향도 커집니다.
그래서 Tool을 제공할 때는 어떤 Tool을 사용할 수 있게 할 것인지도 같이 관리해야 합니다.
3-2. Context
다음은 Context입니다.
Context는 AI에게 어떤 정보를 제공할 것인가입니다.
AI에게 아무리 많은 Tool을 줘도 프로젝트의 구조나 규칙을 모르면 제대로 작업하기 어렵습니다.
그래서 프로젝트의 기술 스택이나 구조, 코딩 규칙 같은 정보를 AI에게 제공해야 합니다.
Claude Code에서는 CLAUDE.md를 통해 이런 내용을 관리할 수 있습니다.
그리고 정보가 너무 많으면 오히려 중요한 정보가 묻힐 수도 있기 때문에,
필요한 정보를 적절하게 제공하는 것도 중요합니다.
3-3. Guardrail
다음은 Guardrail입니다.
Guardrail은 AI가 무엇을 하면 안 되는가를 정하는 겁니다.
AI에게 Tool을 줬다고 해서 모든 행동을 허용하면 위험할 수 있습니다.
그래서 위험한 명령어나 중요한 파일 수정처럼 문제가 될 수 있는 행동에는 제한을 둘 수 있습니다.
또 위험한 작업을 하기 전에 사용자에게 승인을 받도록 만들 수도 있습니다.
즉, AI에게 능력을 주되 위험한 행동에는 제한을 두는 것이 Guardrail입니다.
3-4. 권한과 데이터 관리
다음은 권한과 데이터 관리입니다.
여기서는 AI가 실제로 어디까지 접근할 수 있는가를 관리합니다.
예를 들어 개발 DB에는 접근할 수 있게 하더라도 운영 DB에는 접근하지 못하게 할 수 있습니다.
파일도 마찬가지로 개발에 필요한 파일은 접근할 수 있게 하고,
.env나 API Key 같은 민감한 정보는 접근하지 못하게 할 수 있습니다.
결국 중요한 건 AI에게 필요한 만큼의 권한만 주는 것입니다.
3-5. Monitoring & Feedback
마지막은 Monitoring & Feedback입니다.
AI에게 Tool과 권한을 설정했다고 끝나는 게 아닙니다.
AI가 실제로 어떤 작업을 했는지 확인하고,
문제가 발생하면 왜 문제가 발생했는지 확인해야 합니다.
그리고 같은 문제가 반복된다면 규칙이나 설정을 수정해서 Harness에 반영할 수 있습니다.
즉,
AI의 행동을 확인하고 그 결과를 다시 Harness 개선에 사용하는 것입니다.
3-6. 다섯 가지를 연결해서 보면
지금까지 내용을 한 번에 보면
Tool은 능력
Context는 정보
Guardrail은 제한
권한과 데이터 관리는 접근 범위
Monitoring & Feedback은 확인과 개선
이라고 볼 수 있습니다.
이 다섯 가지가 서로 연결되어 AI Harness를 구성합니다.
그럼 이런 개념들이 실제 개발 도구에서는 어떻게 구현되어 있는지,
저희가 사용하고 있는 Claude Code를 기준으로 보겠습니다.
4. Claude Code에서 AI Harness 구현하기
Claude Code에는 AI Harness와 관련된 여러 기능이 있습니다.
대표적으로
settings.json, CLAUDE.md, Context Window, Skills, Sub-Agent, Hooks
등이 있습니다.
이 기능들이 앞에서 설명한 개념들과 어떻게 연결되는지 보겠습니다.
4-1. settings.json
먼저 settings.json입니다.
settings.json은 Claude Code의 동작 방식이나 권한을 설정하는 파일입니다.
예를 들어 Git 명령어 중에서
git status나 git diff는 허용하고,
git push 같은 작업은 제한할 수 있습니다.
그래서 settings.json은 AI가 어떤 행동을 할 수 있는지 관리하는 설정이라고 볼 수 있습니다.
4-2. CLAUDE.md
다음은 CLAUDE.md입니다.
CLAUDE.md는 AI에게 프로젝트의 구조나 개발 규칙을 알려주는 파일입니다.
예를 들어 기술 스택이나 프로젝트 구조,
그리고 DTO를 사용한다는 것 같은 개발 규칙을 적어둘 수 있습니다.
그러면 매번 AI에게 프로젝트 규칙을 설명하지 않아도 됩니다.
그래서 CLAUDE.md는 앞에서 설명한 Context와 연결되는 기능입니다.
4-3. Context Window
다음은 Context Window입니다.
Context Window는 AI가 한 번의 작업에서 사용할 수 있는 정보의 범위입니다.
여기에는 대화 내용이나 프로젝트 규칙, AI가 읽은 파일, Tool 실행 결과 등이 들어갈 수 있습니다.
그래서 Context가 너무 많아지면 중요한 정보가 묻힐 수도 있습니다.
따라서 필요한 정보를 적절하게 제공하는 것이 중요합니다.
4-4. Skills
다음은 Skills입니다.
개발하다 보면 반복해서 하는 작업들이 있습니다.
예를 들어 커밋처럼 일정한 과정을 반복하는 작업이 있습니다.
이런 과정을 Skill로 만들어두면 하나의 명령으로 정해진 작업 방식을 실행할 수 있습니다.
그래서 Skill은 반복되는 작업을 하나의 워크플로우로 만드는 것이라고 볼 수 있습니다.
4-5. Sub-Agent
다음은 Sub-Agent입니다.
하나의 AI가 모든 작업을 담당하게 하는 대신 역할을 나눌 수 있습니다.
예를 들어 테스트를 담당하는 Agent나 코드 리뷰를 담당하는 Agent를 따로 만들 수 있습니다.
쉽게 말하면 AI의 역할을 나눠서 각각의 작업에 집중시키는 것입니다.
4-6. Hooks
마지막은 Hooks입니다.
Hooks는 AI가 특정 행동을 하기 전이나 후에 정해진 작업을 자동으로 실행하는 기능입니다.
예를 들어 파일을 수정한 뒤 자동으로 포맷팅을 하거나,
위험한 명령어를 실행하기 전에 검사하도록 만들 수 있습니다.
그래서 Hooks는 AI의 행동에 자동으로 개입하는 기능이라고 볼 수 있습니다.
5. The Moment의 AI Harness
그럼 이제 실제로 저희 팀의 AI 하네스를 발표하겠습니다.
5-1. The Moment의 개발 환경
The Moment는 하나의 레포지터리만 사용하는 게 아니라 여러 레포지터리를 사용하고 있습니다.
예를 들어 server와 client가 따로 있고,
팀원마다 Claude Code, Codex, Gemini 등 사용하는 AI 도구도 다를 수 있습니다.
그러다 보니 AI 설정을 어떻게 관리할 것인지가 문제가 됩니다.
5-2. AI 설정 관리에서 발생하는 문제
각 레포지터리마다 AI 설정을 따로 관리한다고 해보겠습니다.
그러면 새로운 규칙이 생겼을 때
각 프로젝트를 찾아가서 설정을 하나씩 수정해야 합니다.
프로젝트가 많아질수록 관리하기 어려워지고,
어떤 프로젝트에는 최신 규칙이 적용되어 있고 다른 프로젝트에는 이전 규칙이 남아있는 문제도 생길 수 있습니다.
5-3. 중앙 관리 방식
저희팀 AI 하네스를 보면 AI 설정을 하나의 중앙 저장소에서 관리합니다.
중앙 저장소를 AI 설정의 기준으로 두고,
각 프로젝트에 필요한 설정을 전달하는 방식입니다.
이렇게 하면 새로운 규칙이 생겨도 중앙 저장소만 수정하면 되고,
팀 전체가 같은 기준을 사용할 수 있습니다.
5-4. GitHub App & GitHub Actions
그럼 중앙 저장소의 변경사항을 어떻게 각 프로젝트에 전달할까요?
AI 하네스를 보면 GitHub App과 GitHub Actions를 사용해서 이 과정을 자동화합니다.
흐름은
중앙 저장소 수정
↓
GitHub Actions 실행
↓
각 프로젝트에 변경사항 반영
↓
PR 생성
입니다.
팀원은 생성된 PR을 확인하고 문제가 없으면 Merge하면 됩니다.
그래서 직접 모든 프로젝트를 찾아가서 수정할 필요가 없습니다.
5-5. 실제 동작 과정
실제로는 이런 식으로 동작합니다.
중앙 저장소에서 CLAUDE.md 같은 설정을 수정합니다.
그리고 GitHub에 Push하면 GitHub Actions가 실행됩니다.
각 프로젝트에 변경사항을 반영하고 PR을 생성합니다.
팀원은 PR을 확인하고 Merge합니다.
그러면 최신 AI 설정이 각 프로젝트에 적용됩니다.
여기서 PR을 사용하는 이유는
변경사항을 바로 적용하지 않고 팀원이 한 번 확인할 수 있기 때문입니다.
7. 마무리
마지막으로 지금까지 내용을 정리해보겠습니다.
AI Harness는 AI가 개발 환경에서 작업할 때
AI의 능력과 행동을 관리하기 위한 환경이라고 볼 수 있습니다.
이를 위해 크게 다섯 가지를 살펴봤습니다.
Tool을 통해 AI가 사용할 수 있는 기능을 정하고,
Context를 통해 프로젝트에 필요한 정보와 규칙을 제공합니다.
그리고 Guardrail을 통해 위험한 행동을 제한하고,
권한과 데이터 관리를 통해 AI가 접근할 수 있는 범위를 정합니다.
마지막으로 Monitoring & Feedback을 통해 AI의 작업 결과를 확인하고,
문제가 발생하면 다시 설정과 규칙을 개선합니다.
그리고 Claude Code에서는
settings.json, CLAUDE.md, Context Window, Skills, Sub-Agent, Hooks
등을 통해 이런 개념들을 실제 개발 환경에 적용할 수 있습니다.
저희 The Moment에서는 여기에 더해서
AI 설정을 중앙 저장소에서 관리하고,
GitHub App과 GitHub Actions를 통해 각 프로젝트에 자동으로 반영하고 PR을 생성하는 방식으로 관리하고 있습니다.
결국 AI Harness는
AI에게 능력을 주는 것에서 끝나는 게 아니라,
그 능력과 정보, 권한, 행동을 함께 관리하는 구조라고 정리할 수 있습니다.
