본 포스팅은 2026년 5월 2일 다바코단 다오랩 바이브코딩 길드에서 '하네스 엔지니어링'에 대한 사례 소개로 발표한 내용입니다.
넥스테인은 SW제품을 가진 기업의 AX에 대한 기술을 개발하고 지원하는 기업으로, 한국 교회 포털인 온맘 닷컴의 시스템운용을 이관 받고, AX에 대한 작업을 진행하고 있습니다. 예전 IDC센터에 있는 레거시 시스템의 이전을 진행하고 프로젝트를 에이전트 기반의 개발 및 운영을 할 수 있는 환경 셋팅을 진행하고, 안정화 및 기능 개선 작업을 진행하고 있습니다. 오래된 레거시 시스템이다 보니 시행 착오가 있고, 이를 naia-business-adk 를 온맘닷컴에 적용하며 기업의 경험과 기술로 체화를 시키고 있습니다. 이에 대한 경험으로서 하네스 엔지니어링을 설명하는 사례로 행사에서 공유했습니다.
이 글의 한 줄 메시지 "AI를 잘 쓰는 것보다, AI가 실수하지 않는 환경을 만드는 게 더 중요하다."
1. 먼저, 우리 서비스 소개
온맘닷컴 — 전국 13,876개 교회가 사용하는 교회 관리 플랫폼
www.onmam.com ← 교회 찾기, 회원 포털
home.onmam.com ← 채널 앱 (콘텐츠/결제)
{교회명}.onmam.com ← 개별 교회 홈페이지
인프라: 구형 IDC 서버 → 2026년 4월 GCP(구글 클라우드) 완전 이전 완료 DB: 13,876개 교회 데이터 × Cloud SQL
2. 사건 하나로 시작하겠습니다
"2026년 4월의 어느 날"
오전 11시. 갑자기 온맘닷컴 전체 서비스 무응답.
사용자들: "사이트 왜 안 돼요?"
원인을 추적했더니 — Board.php 라는 파일의 게시판 목록 조회 코드.
-- 문제가 된 쿼리 (단순화)
SELECT * FROM boards
JOIN (
SELECT bbs_id, COUNT(*) FROM all_boards GROUP BY bbs_id -- ← 이게 문제
) AS summary ON boards.id = summary.bbs_id
WHERE church_id = ?
이 쿼리 하나가 13,876개 교회 전체 데이터를 매번 풀스캔하고 있었다. 트래픽이 몰리자 600~800초짜리 쿼리가 145개 동시 실행 → 서버 완전 마비.
이게 AI와 무슨 관계인가?
이 코드를 처음 작성한 건 아마도 인간 개발자였다. 하지만 오늘날 개발자들은 이런 코드를 AI와 함께 작성한다.
문제는 — AI는 "이 코드가 13,876개 교회 환경에서 어떻게 작동하는지" 모른다. AI는 요청받은 기능을 구현하는 데 집중하고, 우리 서비스의 맥락은 모른다.
그래서 개발자들이 고민하기 시작한 것: "AI가 우리 서비스를 모르는 채로 코드를 짜면 어떻게 막지?"
3. 하네스 엔지니어링 — 30초 설명
말(馬)을 다룰 때 고삐와 마구(Harness)가 필요하듯,
AI 에이전트에게도 제약·가이드·검증 장치가 필요하다.
에이전트 = 모델 + 하네스
하네스 = AI가 일하는 환경 전체를 설계하는 것
단순히 "AI한테 좋은 질문하기"가 아니다. AI가 실수했을 때 구조적으로 같은 실수를 못 하게 만드는 시스템 설계.
4. 온맘닷컴에서 실제로 만든 하네스들
[하네스 #1] AGENTS.md — AI에게 주는 "우리 서비스 지도"
alpha-adk/
├── CLAUDE.md ← AI가 세션 시작할 때 반드시 읽는 파일
├── AGENTS.md ← 프로젝트 규칙 목록
└── .agents/
└── context/
└── agents-rules.json ← 구체적 운영 규칙
AI가 온맘닷컴 코드를 건드리기 전에 반드시 이 파일들을 읽는다. 여기에는 이런 내용이 들어있다:
- "테스트와 코드 수정은 alpha 환경에서만 진행한다"
- "home.onmam.com은 portal이 아닌 별도 channel 앱이다"
- "Board.php에서 GROUP BY 파생 테이블 패턴은 절대 금지"
아까 그 장애? 이제 AI는 같은 패턴을 짜려 하면 이 규칙을 보고 멈춘다.
[하네스 #2] Hooks — AI 행동 전후에 작동하는 "안전장치"
현재 이 워크스페이스에 실제로 동작 중인 훅들:
AI가 Bash 명령 실행하기 직전 →
✓ pr-guard.js : 리뷰 없는 PR 머지 차단
✓ commit-guard.js : 규칙 위반 커밋 차단
✓ deploy-guard.js : 운영 서버 배포 승인 없이 차단
✓ git-push-guard.js : 승인 없는 git push 차단
✓ destructive-git-guard.js : git reset --hard 등 파괴적 명령 차단
AI가 파일 수정하기 직전 →
✓ prod-gateway-guard.js : 운영 API 키를 dev 환경 파일에 못 쓰게 차단
✓ design-doc-guard.js : 설계 문서 무단 수정 차단
AI가 파일 수정한 직후 →
✓ cascade-check.js : 수정된 파일에 연쇄 영향받는 파일 확인
deploy-guard.js 실제 작동 예시:
AI가 운영 배포 명령 실행 시도:
$ gcloud run deploy onmam-web ...
→ [Harness] prod 배포 명령 차단: gcloud run deploy
프로젝트: onmam-web
prod 배포는 사전 승인이 필요합니다.
승인 방법: .claude/deploy/approvals.json에 승인 항목 추가
AI는 prod 배포를 직접 실행하지 않습니다.
AI가 실수로, 또는 너무 적극적으로 운영 서버에 뭔가를 올리려 해도 물리적으로 차단된다.
[하네스 #3] Alpha 환경 — AI가 실험하는 전용 운동장
운영(Production) : www.onmam.com ← 실제 교회들이 사용
스테이징(Staging) : staging.onmampick.org ← 배포 전 최종 확인
알파(Alpha) : luke-*-alpha.onmampick.org ← AI와 함께 작업하는 공간
규칙: AI와 함께 하는 모든 작업은 alpha에서만.
왜 이게 중요한가 — 2026년 4월 29일에 실제로 일어난 일:
AI가
home.onmam.com을portal앱으로 착각해서 잘못된 vhost 설정을 작성. alpha 환경이었기 때문에 → 실제 서비스 영향 없음. 이 실수를 AGENTS.md에 기록 → AI가 같은 실수를 다시 하지 않음.
하네스의 본질이 여기 있다: 실수가 발생하면 → 하네스에 기록 → 다음엔 그 실수가 구조적으로 불가능해진다.
[하네스 #4] Skills — AI에게 주는 "우리만의 도구들"
skills/
├── email/ ← 이메일 발송 (수신자, SMTP 규칙 포함)
├── sms/ ← SMS 발송
├── web-monitoring/ ← 서비스 상태 모니터링
└── service-management/ ← 서비스 운영 명령
AI가 "이메일 보내줘"라고 하면 — 이 스킬 파일을 읽고 누구에게, 어떤 형식으로, 어떤 SMTP로 보내야 하는지 자동으로 안다. 매번 "수신자 이메일 주소가 뭐야?" 물어볼 필요가 없다.
5. 개발자들이 왜 이것에 관심을 갖는가
"AI 없이 개발하던 시대의 문제"
개발자 개인 역량 의존 → 시니어가 빠지면 품질이 떨어짐
코드 리뷰로 잡아야 함 → 사람이 직접 봐야 함
"AI 있는데 하네스 없는 팀의 문제"
AI가 빠르게 코드를 생성하지만 → 우리 서비스 맥락을 모름
같은 실수를 반복함 → 버그는 AI가 만들고 사람이 고침
AI가 운영 서버에 직접 접근 가능 → 언제 사고날지 모름
"AI + 하네스가 있는 팀"
AI가 우리 규칙을 알고 코드를 짬 → 컨텍스트 있는 생성
실수 발생 시 하네스에 기록 → 같은 실수 구조적 방지
운영 접근은 사람이 승인 → 안전한 자율성
토스의 표현을 빌리자면:
"하네스로 조직 전체 생산성의 저점을 끌어올린다. 개인 역량에 의존하지 않고, 모든 팀원이 일정 수준 이상의 결과를 낸다."
6. 정리 — 비개발자에게 전하고 싶은 것
AI 시대에 "잘 한다"의 정의가 바뀌고 있습니다.
예전: 코드를 잘 짜는 개발자 지금: AI가 코드를 짜는 환경을 잘 설계하는 개발자
그 환경 설계의 핵심이 하네스 엔지니어링입니다.
그리고 이건 개발자만의 이야기가 아닙니다.
비개발자도 할 수 있는 하네스:
→ 업무 규칙을 문서로 명확히 쓰는 것
→ AI에게 "이건 해도 되고, 이건 안 된다"를 정의하는 것
→ AI가 실수했을 때 "왜 실수했나"를 기록하는 것
= 이것 자체가 하네스 엔지니어링의 시작
온맘닷컴 하네스 구조 한눈에
alpha-adk/
├── CLAUDE.md ← [Guide] AI 세션 시작 시 필수 독해
├── AGENTS.md ← [Guide] 프로젝트 규칙 (SoT)
├── .agents/context/
│ └── agents-rules.json ← [Guide] 구체적 운영 규칙
├── .claude/
│ ├── hooks/
│ │ ├── deploy-guard.js ← [Sensor] 운영 배포 차단
│ │ ├── prod-gateway-guard.js← [Sensor] 운영 API키 차단
│ │ ├── commit-guard.js ← [Sensor] 커밋 규칙 검증
│ │ ├── pr-guard.js ← [Sensor] PR 승인 강제
│ │ ├── session-inject.js ← [Sensor] 매 세션 컨텍스트 주입
│ │ └── cascade-check.js ← [Sensor] 수정 후 연쇄 영향 확인
│ └── settings.json ← [Permission] 훅 실행 설정
├── skills/
│ ├── email/ ← [Tool] 이메일 발송 스킬
│ ├── web-monitoring/ ← [Tool] 서비스 모니터링
│ └── service-management/ ← [Tool] 서비스 운영 명령
└── data-private/memory/ ← [Feedback Loop] 실수 기록 → 재발 방지
├── project_onmam_incidents.md ← Board.php 장애 패턴 기록
├── project_onmam_app_structure.md← home≠portal 실수 기록
└── feedback_alpha_only.md ← alpha 전용 규칙 기록
하네스 = 이 파일들의 집합 모두 git 레포에 커밋된다. 팀의 모든 맥락!이 코드로 축적된다.
