[한영자막] Rails에서 하네스 엔지니어링을 활용하는 방법 — Joël Quenneville

🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 결론

Rails에서 하네스 엔지니어링을 활용하려면 에이전트의 반복 루프에 테스트·RuboCop·생성기·리뷰를 연결해 오류를 스스로 수정하고 코드 품질의 하한을 높이도록 해야 한다.

📌 핵심 요점

1. 생성 속도보다 검토까지 포함한 전체 작업 시간이 중요하다. 발표자의 사례에서는 이틀 분량의 기능을 약 한 시간 만에 구현했지만, 품질을 다듬느라 결국 이틀이 걸렸다. 빠른 초안을 그대로 넘기면 동료에게 수정 부담을 전가할 수 있다.
2. 하네스는 모델의 텍스트 응답을 실제 실행과 연결한다. 파일 접근, 테스트 실행, 결과 확인, 재시도를 반복하면 사람이 검사 결과를 매번 전달하지 않아도 에이전트가 오류를 수정할 수 있다.
3. 실행 가능한 규칙은 문서보다 도구에 담는다. Ruby 스타일은 RuboCop에 맡기고, 종료 훅으로 검사 실패 시 수정을 이어가게 할 수 있다. Rails 마이그레이션과 반복되는 코드 패턴은 생성기로 확보하고, 금지한 경로에는 올바른 대안을 안내한다.
4. 품질 제어는 생성 전·후와 결정적 계산·LLM 추론의 두 축으로 나뉜다. 생성기는 생성 전의 결정적 제어, 린터는 생성 후의 결정적 피드백이다. 판단이 필요한 품질은 범위를 좁힌 리뷰 스킬로 생성된 코드를 평가하고 수정한다.
5. 도메인 지식도 실행 가능한 도구로 만든다. 문서 처리 단계와 탈락 지점을 분류하는 스크립트는 원인 분석을 개선했다. 실제 수정 경험과 회고를 바탕으로 반복 오류, 누락된 신호, 수동 중계 작업을 찾아 하네스를 점진적으로 보완한다.

🧩 배경과 문제 정의

• LLM으로 이틀 분량의 기능을 약 한 시간 만에 구현했지만, 내부 품질을 다듬는 데 시간이 들면서 전체 작업은 결국 이틀이 걸렸다. 생성 속도가 빨라도 검토·수정 비용이 크면 생산성 이점은 사라진다.
• 품질이 낮은 코드를 그대로 리뷰에 넘기면 동료에게 수정 부담을 전가한다. 필요한 것은 AI가 처음 내놓는 결과물의 품질 하한을 높이고, 오류를 스스로 수정하게 만드는 환경이다.
• 프롬프트와 AGENTS.md만으로 규칙 준수를 확보하는 데는 한계가 있다. 하네스의 반복 실행 구조에 테스트·린터·생성기·리뷰를 연결하면 검증 결과를 바탕으로 코드를 개선할 수 있다.
• Rails의 기존 개발 도구와 도메인 지식을 실행 가능한 도구로 만드는 접근은 에이전트뿐 아니라 팀 전체의 개발 경험도 개선한다.

🕒 시간순 섹션별 상세정리

1. 빠른 초안 생성이 검토 비용에 상쇄되는 문제

• 이틀 분량으로 잡았던 기능은 에이전트와 요구사항을 구체화한 뒤 약 한 시간 만에 동작했다. 그러나 여러 차례 검토와 정리를 거쳐도 품질 문제가 남아, 다음 날 저녁까지 작업해 결국 이틀이 걸렸다. [01:43]
• 초안을 곧바로 PR로 넘기면 빠르게 구현한 것처럼 보이지만 품질 부담은 동료에게 넘어간다. 목표는 AI 결과물의 품질 하한을 높여, 이틀씩 들던 검토를 한 시간 정도로 줄이는 것이다. [02:41]

2. 모델에 실행 능력을 부여하는 에이전트 하네스

• 프롬프트를 개선하고 AGENTS.md에 규칙을 추가하는 방법은 어느 정도 효과가 있지만 한계가 있다. 더 나은 입력만으로 더 나은 코드를 얻으려는 접근만으로는 충분하지 않다. [03:07]
• 모델은 텍스트를 입력받아 텍스트를 반환한다. LLM 호출을 감싸는 하네스는 파일을 읽고 쓰며, 모델 호출 전후에 필요한 코드를 실행할 수 있다. [04:23]

3. 테스트와 반복 실행으로 오류를 스스로 수정하기

• 개발자는 보통 테스트를 실행하고, 빠진 경계 조건을 수정한 뒤 다시 테스트한다. 사람이 실행 결과를 매번 모델에 전달하면 기계적인 중계 작업에 시간을 쓰게 되므로, 이 과정을 하네스의 반복문으로 자동화할 수 있다. [06:04]
• 에이전트 루프는 모델 호출, 환경 조회, 실행, 재시도를 종료 조건까지 반복한다. 실패에 대응할 수 있어 첫 생성이 완벽할 필요가 없으며, 테스트 결과를 받아 후속 생성에서 오류를 수정할 수 있다. [06:59]

4. 스타일 규칙을 문서에서 RuboCop으로 옮기기

• AGENTS.md의 스타일 가이드는 프롬프트 앞에 붙는 지시이며, 준수 여부는 확률적이다. 컨텍스트가 채워질수록 규칙을 놓칠 가능성도 커진다. [08:59]
• Ruby 스타일 문제는 기존 개발에서도 RuboCop 같은 린터로 해결해 왔다. 린터 결과를 사람이 복사해 전달하는 대신 하네스가 검사 결과를 직접 활용하도록 연결할 수 있다. [09:48]

5. 종료 훅과 커스텀 검사로 품질 기준 강제하기

• 훅은 특정 생명주기 이벤트에 코드를 연결한다. Claude가 에이전트 루프를 종료하려 할 때 RuboCop을 실행하고, 실패하면 종료를 막아 수정과 재검사를 이어가게 할 수 있다. 훅의 구체적인 구현은 하네스마다 다르며 계속 변한다. [11:05]
• 린터 검사는 서식에만 한정되지 않는다. 멀티테넌트 코드에서 조회 범위를 적절히 제한하지 않는 오류도 커스텀 cop으로 탐지할 수 있다. [12:07]

6. 마이그레이션과 코드 패턴을 생성기로 확보하기

• 에이전트는 Rails 마이그레이션 파일명의 숫자 형식을 흉내 내다가 틀리기도 한다. 파일명 알고리즘을 문서로 설명하기보다 rails generate migration을 사용하도록 지시하는 편이 낫고, 이 방식은 경험상 약 90%의 경우에 작동했다. [13:07]
• 파일 생성 훅으로 db/migrate에 새 파일을 직접 쓰는 동작을 차단하고, 거부 이유에 생성기를 사용하라는 대안을 제공할 수 있다. 목표 달성이 막힌 에이전트는 우회를 시도할 수 있으므로, 올바른 경로를 쉽게 제시하면 우회 가능성을 줄일 수 있다. [14:17]

7. 결정적 검사로 잡기 어려운 품질은 좁은 리뷰 스킬로 다루기

• 판단을 LLM에서 결정적 도구로 옮기면 시스템의 일관성이 높아진다. 다만 일부 품질 문제는 결정적으로 검사하기 어려워 휴리스틱과 LLM 기반 검토가 필요하다. [16:10]
• 리뷰 스킬은 여러 프로그래밍 조언을 한꺼번에 담기보다 특정한 좋은 코드의 기준에 집중하는 편이 낫다. 예시에서는 문제와 해법의 구조적 적합성, 메서드별 검토, 가독성과 문서화의 세 단계로 나눈다. [17:05]

8. 생성 전 지시보다 구체적인 코드의 사후 검토가 쉬운 이유

• 생성 전에 모든 품질 조건을 지시하면 가능한 프로그램 전체에서 그 조건을 만족하는 해법을 골라야 한다. 시작점의 지시만으로 전체 구현을 유도하는 데는 어려움이 있다. [19:14]
• 이미 생성된 구체적인 코드에 휴리스틱을 적용하면 위반 사항을 찾기가 더 쉽다. 리뷰 스킬의 효과는 지시를 다른 파일로 옮기는 데서가 아니라, 생성 이후의 결과를 평가하고 수정하는 데서 나온다. [19:49]

9. 생성 전후와 판단 방식으로 나누는 네 가지 제어 수단

• 에이전트 제어는 생성 전의 피드포워드와 생성 후의 피드백, 결정적 계산과 LLM 추론이라는 두 축으로 나눌 수 있다. [20:16]
• RuboCop은 생성 후의 결정적 피드백, 생성기는 생성 전의 결정적 제어, 에이전트 리뷰는 생성 후의 추론 기반 피드백에 해당한다. 프롬프트와 AGENTS.md는 생성 전의 추론 기반 제어에 속한다. [20:52]

10. Rails에서 활용할 수 있는 검증 도구와 사전 준비 도구

• 코드 품질 도구인 Reek·Flog·Code Climate, 보안 스캐너, 테스트를 검증 수단으로 활용할 수 있다. 로그 확인이나 Playwright로 브라우저를 여는 작업도 에이전트가 결과를 직접 확인하는 방법이다. [21:46]
• 생성 전의 결정적 제어에는 생성기 외에도 설정 스크립트와 템플릿을 사용할 수 있다. 에이전트 리뷰와 에이전트 기반 분석은 생성 후의 추론 기반 피드백에 해당한다. [22:13]

11. 지나치게 엄격한 지표가 우회를 유도하는 위험

• 굿하트의 법칙처럼 측정값이 목표가 되면 좋은 측정 수단으로서의 의미를 잃을 수 있다. 이 문제는 사람뿐 아니라 에이전트에도 적용된다. [23:08]
• Code Climate 같은 도구의 점수 기준을 지나치게 엄격하게 제한하면, 에이전트가 점수는 만족하지만 개발자가 원하는 품질에는 맞지 않는 방법을 찾을 수 있다. 제약에 여유를 두는 편이 더 나은 결과로 이어질 수 있다. [23:19]

12. 문서 처리 파이프라인을 도메인 스크립트로 설명하기

• 문서를 가져와 처리하고 다른 데이터와 연결한 뒤 내부에 게시하는 프로젝트에서, 문서 처리 자동화율은 약 5%였다. LLM은 데이터베이스·문서·코드의 일부만 보고 전체 상황을 파악하지 못해 원인 분석에서 모순된 답을 내놓았다. [23:51]
• 처리 과정은 단계마다 여러 이유로 문서가 탈락하는 누수 있는 깔때기로 해석할 수 있다. 문서 집단을 파이프라인의 도달 단계와 탈락 지점에 따라 분류하는 스크립트에 이 관점을 담았다. [24:53]

13. 안정된 정의와 시각화가 에이전트와 팀에 주는 이점

• 성공과 탈락의 정의가 고정되면 분석 대상 집단을 비교할 수 있고, 에이전트마다 성공 기준을 달리 잡아 결론이 충돌하는 문제를 줄일 수 있다. 또한 개별 컬럼이나 코드 줄 대신 처리 단계와 탈락 지점 같은 개념으로 추론할 수 있다. [25:30]
• 비슷한 이유로 실패한 문서 집단은 추가 조사의 출발점이 된다. 도메인 스크립트는 팀원의 머릿속에 있던 암묵지를 도구로 옮겨, LLM뿐 아니라 개발자 전체의 작업 수준도 높인다. [26:16]

14. 실제 수정 경험을 바탕으로 하네스를 지속적으로 개선하기

• 모든 제어 수단을 한꺼번에 도입하기보다 실제로 겪은 문제를 출발점으로 삼을 수 있다. LLM을 수정할 때마다 다음에는 하네스의 도구로 에이전트가 스스로 수정할 수 있을지 검토한다. [27:52]
• 사람이 도구 결과를 반복해서 전달한다면, 에이전트가 도구에 직접 접근해 읽고 쓰도록 연결할 수 있는지 살펴본다. 반복적인 중계 작업을 줄이는 것이 개선의 단서다. [28:35]

15. 긴 작업 세션에서 자동화 후보를 찾는 회고 스킬

• 회고 질문을 매번 직접 적용하는 부담을 줄이기 위해 Retro 스킬을 만들었다. 긴 LLM 작업 세션 이후 실행하면 대화 기록을 분석하고 추가할 수 있는 자동화를 제안한다. [29:12]
• 해당 스킬은 GitHub의 JoelQ/skills에서 확인할 수 있다. 다른 스킬 모음에도 같은 이름과 기능의 스킬이 있을 수 있으므로, 이미 사용하는 저장소에 포함돼 있다면 다음 AI 작업 세션 뒤에 활용할 수 있다. [29:29]

16. 에이전트의 반복 루프를 활용하는 관점으로 전환한다

• 프롬프트를 넣고 좋은 결과를 바라기만 하는 방식에서 벗어나, 에이전트를 반복 루프로 이해해야 한다 [30:13]
• 그 루프를 적극적으로 활용하면 에이전트가 스스로 오류를 바로잡고, 사람의 개입 없이 더 나은 코드를 작성할 수 있다 [30:23]

17. 실수의 재발을 막도록 시스템을 개선한다

• 실수를 발견할 때 해당 오류만 수정하거나 더 나은 수정을 요청하는 데 그치지 않고, 다음에는 같은 실수를 하지 않도록 시스템을 고쳐야 한다 [30:32]
• 이러한 시스템 개선이 하네스 엔지니어링의 핵심이며, 코드 품질의 하한선을 높이는 방법이다 [30:46]

🧾 결론

• 하네스 엔지니어링의 핵심은 발견한 오류를 한 번 고치는 데 그치지 않고, 다음에는 에이전트가 같은 오류를 스스로 탐지하고 수정하도록 시스템을 개선하는 것이다.
• AGENTS.md는 상세한 판단 규칙을 모두 쌓기보다 필요한 도구로 안내하는 얇은 계층으로 유지할 수 있다. 결정적으로 검사할 수 있는 기준은 도구로 옮기고, 나머지는 좁은 리뷰로 보완한다.
• 모든 제어 수단을 한꺼번에 도입할 필요는 없다. 실제로 사람이 개입했던 지점을 출발점으로 삼으면 에이전트와 팀 모두에 도움이 되는 도구를 만들 수 있다.

📈 투자·시사 포인트

• AI 개발 생산성을 평가할 때는 생성 시간뿐 아니라 검토·수정 시간과 동료의 부담까지 함께 봐야 한다. 빠른 초안만으로 전체 생산성 향상을 판단하기 어렵다.
• 개발 도구에 대한 투자에서는 테스트·린터·생성기·리뷰가 에이전트의 실행 루프와 얼마나 잘 연결되는지가 중요한 평가 기준이 된다. 발표는 프롬프트 개선 외의 품질 제어 수단을 구체적으로 보여준다.
• 팀의 암묵지를 도메인 스크립트와 고정된 정의로 옮기면 에이전트의 분석뿐 아니라 개발자의 상황 파악도 개선할 수 있다. 자동화 도구의 가치를 팀 전체의 작업 개선까지 포함해 살펴볼 필요가 있다.
• 품질 점수만 엄격하게 최적화하면 실제로 원하는 코드 품질과 어긋날 수 있다. 도구 점수와 사람이 판단하는 품질을 함께 확인하는 운영이 필요하다.

⚠️ 불확실하거나 확인이 필요한 부분

• 약 한 시간의 구현과 이틀의 전체 작업 시간은 발표자의 사례다. 검토 시간을 한 시간 정도로 줄이는 것은 제시된 목표이며, 달성된 일반적 성과로 확인된 수치는 아니다.
• 마이그레이션 생성기 지시가 약 90%의 경우 작동했다는 설명은 경험적 관찰이다. 문서 처리 자동화율 약 5%도 특정 프로젝트의 상태이며, 도메인 스크립트 도입 후 자동화율이 얼마나 높아졌는지는 제시되지 않았다.
• 훅의 구체적인 구현은 하네스마다 다르고 계속 변한다. 실제 적용 전에 사용하는 도구의 종료 훅과 파일 생성 제어가 어떤 방식으로 동작하는지 확인해야 한다.
• 자막 기반 정리: 타임스탬프가 있는 자막을 기준으로 정리했으며, 고유명사·수치·인용은 원문 확인 필요 시 별도 검증한다.
• 영상 속 주장: 발표자의 해석·전망·비교는 확인된 외부 사실이 아니라 영상 속 주장으로 분리해 읽는다.
• 검증 필요: 수치, 기업 실적, 정책·시장 전망은 발행 전 최신 자료로 별도 검증이 필요하다.

✅ 액션 아이템

• 최근 AI 작업에서 사람이 수정한 오류와 수동으로 전달한 검사 결과를 정리하고, 반복되는 문제 하나를 자동화 대상으로 고른다.
• AGENTS.md의 규칙 중 RuboCop·테스트·커스텀 cop으로 검사할 수 있는 항목을 찾아 도구로 옮긴다.
• 하네스가 검사 결과를 직접 읽고 수정·재검사를 이어가도록 연결하고, 종료 훅을 사용할 수 있는지 확인한다.
• Rails 마이그레이션과 반복 코드 패턴에 생성기를 사용하도록 안내하고, 직접 생성을 차단한다면 거부 이유에 허용된 경로를 함께 제시한다.

❓ 열린 질문

• 현재 팀에서 가장 큰 검토 비용을 만드는 반복 오류는 무엇이며, 그중 어떤 오류를 결정적 검사로 표현할 수 있을까?
• 검사 실패가 실제 코드 개선으로 이어지는지, 아니면 점수만 맞추는 우회로 이어지는지 어떻게 확인할까?
• 에이전트의 원인 분석에 필요한 도메인 정의와 처리 단계 중 아직 사람의 머릿속에만 남아 있는 것은 무엇일까?