하네스 엔지니어링 적용 후기

왜 하네스 엔지니어링이 필요했나

AI와 함께 개발할 때 자주 부딪히는 문제는 모델 성능 그 자체보다 문맥 유지였다.
특히 작업이 길어지거나, 세션이 바뀌거나, 구조가 조금만 복잡해져도 같은 설명을 계속 반복하게 된다.

처음에는 나도 프롬프트를 길게 적는 방식으로 해결하려고 했다.

이 프로젝트는 어떤 구조인지
무엇을 먼저 봐야 하는지
어떤 변경은 조심해야 하는지
작업 문서는 어디에 남겨야 하는지
언제 보조 도구를 쓰고, 언제 쓰지 말아야 하는지

그런데 이 방식은 금방 한계가 왔다.
세션이 바뀌면 다시 설명해야 하고, 작업이 커질수록 프롬프트는 길어지는데 정작 중요한 프로젝트 규칙은 쉽게 흩어졌다.

그래서 이번에는 프롬프트를 더 길게 쓰는 대신, 프로젝트 안에 에이전트용 레일을 먼저 깔아두는 쪽을 선택했다.
내가 이번에 적용한 하네스 엔지니어링은, AI가 프로젝트 안에서 길을 잃지 않도록 진입점, 참조 순서, 작업 문서, 보조 도구의 우선순위를 저장소 안에 명시하는 방식에 가깝다.

문서 핵심 순서

이번에 핵심으로 둔 문서는 아래 네 종류였다.

AGENTS.md
ARCHITECTURE.md
docs/exec-plans/*
docs/adr/*

여기서 가장 중요한 문서는 AGENTS.md 다.
예전에는 AGENTS.md 를 단순 규칙집처럼 생각했는데, 이번에는 아예 에이전트의 진입 프롬프트처럼 설계했다.

즉, AGENTS.md 안에 아래 내용을 넣었다.

작업 시작 전에 무엇을 먼저 읽어야 하는지
다음으로 어떤 문서를 읽어야 하는지
기존 작업 문서가 있으면 새 문서를 만들기 전에 먼저 확인해야 한다는 점
언제 exec plan 을 만들고 갱신해야 하는지
언제 ADR 로 올려야 하는지
실제 코드를 보기 전에 어떤 영향 범위를 먼저 판단해야 하는지
gstack skill 은 어디까지 보조 도구인지
프로젝트 문서와 보조 스킬 사이의 우선순위

결국 AGENTS.md 는 “이렇게 해라”를 적어두는 문서가 아니라, 다른 md 파일을 읽게 만들고 그 위에서 내가 정한 규칙을 실행하게 만드는 시작점이 됐다.
아래는 현재 프로젝트 구조이다. 하네스_패키지.png

AGENTS.md를 어떻게 진입점으로 만들었나

이번에 가장 신경 쓴 부분은 AGENTS.md 가 혼자 모든 것을 설명하려고 하지 않게 만드는 것이었다.
대신 AGENTS.md 는 다음 문서로 에이전트를 보내는 라우터 역할을 하게 했다.

흐름은 대략 이런 식이다.

AGENTS.md
-> ARCHITECTURE.md
-> docs/exec-plans/*
-> docs/adr/*
-> 실제 코드
-> 필요 시 gstack skill 사용

이 순서를 넣은 이유는 단순하다.

AGENTS.md 만 읽으면 규칙은 알 수 있어도 현재 구조는 부족할 수 있다.
반대로 코드만 먼저 읽으면 프로젝트의 금지 사항이나 작업 문서 운영 방식이 빠질 수 있다.

그래서 이번에는:

AGENTS.md 에서 작업 방식과 우선순위를 잡고
ARCHITECTURE.md 에서 현재 구조와 책임을 확인하고
docs/exec-plans 와 docs/adr 에서 과거 작업 문맥과 구조적 결정을 읽고
마지막에 실제 코드를 보게 만드는 흐름

으로 정리했다.

이 방식이 좋았던 이유는, 에이전트가 처음부터 “바로 코드를 고치러 들어가는 습관”을 줄여줬기 때문이다.
먼저 문서를 읽고, 그 다음에 구현에 들어가게 되니 작업 품질이 훨씬 안정적이었다.

내가 실제로 어떻게 쓰고 있나

지금 내가 실제로 쓰는 흐름도 거의 그대로다.

새 작업이 들어오면 보통 아래 순서로 진행한다.

먼저 AGENTS.md 를 읽게 한다.
거기 적힌 순서대로 ARCHITECTURE.md 와 관련 작업 문서를 읽게 한다.
기존 exec plan 이 있으면 이어서 쓰고, 없으면 새로 만든다.
구조적인 결정이 필요하면 ADR 로 올릴지 판단한다.
실제 구현에 들어간다.
구현이 끝나면 검증과 기록을 남긴다.

이 흐름의 핵심은 “내가 머리로 기억하는 운영 방식”을 문서로 옮겨놨다는 점이다.
예전에는 내가 직접 프롬프트로 통제해야 했다면, 지금은 프로젝트 안에 이미 다음 행동이 적혀 있다.

즉, 내가 하네스 엔지니어링을 적용하면서 바꾼 것은 코드 구조보다 작업 진입 방식에 더 가까웠다.

내가 생각한 프롬프트 동작 방식

이번에 문서를 만들면서 특히 의식했던 것은 “이 문장을 사람이 읽는 게 아니라, 모델이 순서대로 문맥을 먹는다는 점”이었다.

그래서 AGENTS.md 를 쓸 때도 일반적인 가이드 문서처럼 쓰지 않았다.
필요한 정보만 적는 게 아니라, 프롬프트가 실제로 어떻게 동작할지를 생각하고 순서를 설계했다.

예를 들면 이런 식이다.

먼저 무엇을 읽을지 적는다.
다음에 어떤 문서를 읽을지 적는다.
작업 문서가 있으면 새로 만들지 말고 먼저 보라고 적는다.
구조적 판단은 ADR 로 올릴지 검토하라고 적는다.
보조 스킬은 프로젝트 문서를 덮어쓰지 못하게 우선순위를 낮게 둔다.

이렇게 해두면 모델이 단순히 규칙을 읽는 게 아니라, “다음에 무엇을 해야 하는지”까지 이어서 행동하게 된다.

개인적으로는 이 부분이 가장 하네스 엔지니어링답다고 느껴졌다.
문서를 저장해둔 것이 아니라, 프로젝트 안에 작은 실행 흐름을 심어둔 셈이기 때문이다.

gstack은 왜 같이 붙였나

하네스 엔지니어링만으로도 기본적인 레일은 만들 수 있다.
그런데 실제 작업을 해보면, 문서만으로 해결되지 않는 부분이 있다.

요구사항이 아직 애매한 작업
구현은 끝났지만 리뷰가 필요한 작업
화면은 바뀌었지만 실제로 QA가 필요한 작업
작업 후 문서까지 같이 정리해야 하는 작업
문제 원인부터 다시 파고들어야 하는 작업

이런 부분까지 더 안정적으로 다루기 위해 gstack 을 도입했다.

다만 여기서 중요한 건, gstack 을 메인 규칙으로 두지 않았다는 점이다.
이번에는 gstack 을 어디까지나 보조 엔진처럼 붙였다.

즉, 순서는 이렇게 잡았다.

프로젝트 문서 우선
-> 필요한 경우에만 gstack skill 호출
-> 결과는 다시 프로젝트 문서와 코드 기준으로 판단

이렇게 한 이유는 범용 스킬이 프로젝트 고유 규칙을 덮어쓰지 않게 하기 위해서다.
보조 도구는 강력할수록 좋지만, 프로젝트 문맥 위에서만 힘을 써야 한다.

gstack을 붙였더니 실제로 뭐가 좋아졌나

프롬프트 샘플.png

1. 애매한 작업을 바로 구현으로 밀어붙이지 않게 됐다

계획이 필요한 작업에서는 관련 planning skill 을 먼저 검토하게 만들었다.
덕분에 구현 전에 범위, 영향, 우선순위를 한 번 더 정리하게 됐다.

이건 생각보다 중요했다.
AI는 바로 코드를 쓰는 데 강하지만, 그게 항상 좋은 시작은 아니다.
특히 구조 변화가 있는 작업은 먼저 정리하는 단계가 있어야 뒤가 덜 흔들린다.

2. 코드 작성과 리뷰를 분리하기 쉬워졌다

작업을 마친 뒤 review 계열 skill 로 한 번 더 보게 만들면, “잘 돌아간다”와 “안전하게 들어갈 수 있다”를 분리해서 볼 수 있었다.

이전에는 구현이 끝나면 곧바로 마무리하기 쉬웠는데, 지금은 리뷰가 별도 단계로 들어오면서 놓치는 부분이 줄었다.

3. QA를 프롬프트 의존이 아니라 작업 단계로 넣을 수 있었다

브라우저 기반 QA나 보고서형 QA를 어떤 경우에 붙일지 AGENTS.md 안에 같이 적어두니, 테스트가 선택 사항이 아니라 작업 흐름의 일부가 됐다.

이건 체감이 컸다.
특히 화면 작업은 “눈으로 보면 되겠지”로 끝나기 쉬운데, QA가 명시된 순간부터는 검증도 작업의 일부가 됐다.

4. 작업 후 문서 정리가 쉬워졌다

문서를 손으로 끝까지 다듬는 일은 자주 밀린다.
그런데 document-release 같은 정리 계열 흐름을 보조로 붙여두니, 코드만 바뀌고 문서는 낡아가는 문제를 줄이기 쉬웠다.

5. 조사성 작업의 진입 비용이 줄었다

원인 파악이 먼저 필요한 작업은 보통 손대기 귀찮다.
이번에는 조사 계열 skill 을 어디에 붙일지 미리 정해두니, 막히는 순간 다시 조사 단계로 돌아가기가 쉬워졌다.

결국 gstack 을 붙인 효과는 “더 똑똑한 답변” 그 자체보다, 하네스 위에서 계획, 리뷰, QA, 정리 단계를 더 자연스럽게 호출할 수 있게 된 점에 있었다.

적용하면서 좋았던 점

1. 프롬프트를 덜 설명하게 됐다

예전에는 매번 “이 프로젝트에서는 뭘 먼저 봐야 하고, 어떤 변경은 조심해야 하고, 문서는 어디에 남겨야 한다”를 장황하게 설명했다.

지금은 그 설명이 프로젝트 안으로 들어왔다.
즉, 내 운영 규칙이 채팅창 안에만 있는 게 아니라 저장소 안에 남게 됐다.

2. 세션이 바뀌어도 다시 출발하기 쉬워졌다

AGENTS.md 가 진입점 역할을 하니, 세션이 끊겨도 다시 같은 출발점으로 돌아오기가 쉬웠다.
이건 혼자 작업할 때도 좋았고, 다른 에이전트나 다른 도구를 붙일 때도 좋았다.

3. 문서가 설명서가 아니라 작업 인터페이스가 됐다

이번에 가장 크게 느낀 부분이다.
잘 만든 AGENTS.md 는 읽고 끝나는 문서가 아니라, 다음 행동을 유도하는 인터페이스에 가깝다.

무엇을 먼저 읽고, 어떤 범위를 먼저 확인하고, 언제 새 문서를 만들고, 어떤 경우에 스킬을 꺼낼지가 드러나기 때문이다.

4. 프로젝트 고유 규칙과 범용 스킬을 분리할 수 있었다

이전에는 범용 도구를 강하게 쓰면 프로젝트 고유 규칙이 밀리는 경우가 있었다.
이번에는 우선순위를 명시해두니, 범용 스킬은 보조 도구로 남고 프로젝트 문서가 기준점을 유지할 수 있었다.

시행착오도 있었다

물론 처음부터 만족스러웠던 건 아니다.

1. AGENTS.md에 너무 많은 정보를 넣으면 오히려 무거워진다

처음에는 모든 규칙을 한 문서에 다 넣고 싶었다.
그런데 그렇게 하면 AGENTS.md 가 규칙집이면서 구조 문서이면서 작업 로그 문서가 되어버린다.

그래서 지금은 AGENTS.md 는 진입과 우선순위, ARCHITECTURE.md 는 현재 구조, exec plan 은 작업 메모, ADR 은 결정 기록으로 나눠 쓰는 쪽이 더 잘 맞는다고 보고 있다.

2. 작은 변경까지 다 ADR로 올리면 오히려 안 쓰게 된다

구조적 결정만 ADR 로 남기고, 작은 작업은 exec plan 수준에서 끝내는 기준을 잡아야 실제로 유지가 된다.
이 선을 못 잡으면 문서화 자체가 귀찮은 의식처럼 변한다.

3. 문서는 계속 맞춰줘야 한다

하네스 엔지니어링은 한 번 깔아두면 끝나는 게 아니다.
구조가 바뀌었는데 문서를 안 고치면, 그 순간부터 가드레일이 아니라 잘못된 힌트가 된다.

그래서 결국 중요한 건 “문서를 만들었다”가 아니라 “문서를 계속 현재형으로 유지할 수 있느냐”였다.

지금 기준의 사용 패턴

지금 나는 하네스 엔지니어링을 대략 이렇게 쓰고 있다.

AGENTS.md 를 진입점으로 둔다.
AGENTS.md 가 다음에 읽어야 할 md 를 안내하게 만든다.
기존 작업 문서가 있으면 이어서 보고, 없으면 새로 만든다.
구조적 결정은 ADR 로 분리한다.
계획, 리뷰, QA, 문서 정리처럼 범용성이 큰 작업만 gstack 을 붙인다.
최종 판단은 항상 프로젝트 문서와 실제 코드 기준으로 다시 확인한다.

이 패턴이 좋은 이유는, AI를 그냥 “잘 코딩하는 도구”로 두는 게 아니라 프로젝트 안에서 일하는 작업자로 다루게 해준다는 점이다.
그리고 그 작업자가 길을 잃지 않게 만드는 손잡이가 바로 AGENTS.md 였다.

마무리

이번에 하네스 엔지니어링을 적용하면서 가장 크게 느낀 건, 좋은 프롬프트는 채팅창에만 있지 않아야 한다는 점이었다.

정말 중요한 규칙이라면 프로젝트 안에 남아 있어야 하고, 에이전트가 실제로 그 규칙을 따라 움직일 수 있어야 한다.
그래서 이번에는 AGENTS.md 를 진입점으로 두고, 그 문서가 다른 md 를 읽게 하고, 필요한 스킬을 꺼내 쓰게 하고, 마지막에는 다시 프로젝트 문서와 코드로 돌아오게 만드는 흐름을 설계했다.

아직 더 다듬을 부분은 있다.

더 가벼운 문서 진입 구조 만들기
실제 작업 사례를 더 축적하기
문서 갱신 자동화 보강하기

그래도 지금 기준에서는, 이 방식이 적어도 “작업 시작할 때마다 프로젝트를 다시 설명해야 하는 비용”을 많이 줄여줬다.
개인적으로는 그 점 하나만으로도 충분히 적용할 가치가 있었다.