2026 - AX - NHN Cloud, AI 팀원을 위한 하네스 제작

https://meetup.nhncloud.com/posts/423

2026.09.28
[나는 하네스 깎는 노인이 되었다 시리즈 1: 은총알은 없다]

이 글은 인공지능을 완벽한 동료로 활용하기 위해서는 체계적인 맥락과 구조를 스스로 구축해야 한다는 점을 다루고 있다. 저자는 단순히 AI 모델의 성능에 기대기보다 서비스 지식을 명확히 분류하고, 작업 이력을 신중하게 기록하며, 위험 요소를 원천 차단하는 규칙을 세우는 과정이 필수적이라고 강조한다. 결국 AI 도구의 깊이 있는 활용은 하루아침에 주어지는 은총알이 아니라 사람이 직접 깎아 나가는 노력에서 비롯된다는 교훈을 전하고 있다.

 

 

이 글의 핵심은 “좋은 프롬프트를 작성하는 것”을 넘어, AI가 업무 맥락을 찾아 쓰고, 검증된 경험을 축적하며, 실수하더라도 피해가 제한되도록 업무 환경을 설계해야 한다는 것입니다.

• 작성자: 이재형, NHN Cloud 메시징플랫폼개발팀
• 등록일: 2026년 9월 28일
• 성격: 한 달간 하네스를 직접 구축·개선한 실무 경험담입니다. 통제된 성능 실험이나 일반화된 표준 아키텍처를 제시한 글은 아닙니다.[1]

아래는 원문의 실제 챕터 순서를 따르며, 원문 내용과 분석·보완 의견을 구분했습니다.

 

1. 들어가며 — AI를 ‘매일 처음 출근하는 직원’에서 ‘맥락을 아는 동료’로

원문 핵심

저자는 AI 세션을 새로 열 때마다 팀의 서비스, 코드 저장소, 배포 절차 등을 다시 설명하는 상황을 문제로 제시합니다. 목표는 코드만 작성하는 도구가 아니라, 팀의 운영 맥락을 이미 알고 업무를 수행하는 동료에 가까운 AI를 만드는 것입니다.[1]

여기서 출발점은 모델의 지능 부족보다 세션 간 업무 맥락의 단절입니다.

기술적 의미

이 글에서 하네스는 단일 프롬프트라기보다 다음 요소를 묶은 AI 업무 수행 환경으로 해석할 수 있습니다.

구성 요소	역할
진입 문서	AI가 무엇을 먼저 확인할지 안내
팀·서비스 지식	업무 대상과 운영 기준 제공
작업·결정·사고 기록	이전 경험과 판단 근거 제공
실행 스크립트	도구 접근 경로 정형화
권한 제한	잘못된 행동의 영향 범위 제한

이는 원문의 구성 요소를 종합한 분석적 정리이며, 저자가 제시한 공식 정의는 아닙니다.

중요한 전환은 다음과 같습니다.

매번 사람이 맥락을 설명하는 방식 → AI가 필요한 맥락을 찾아가는 방식

 

한계와 실무 시사점

[확인 필요] ‘팀원처럼 일한다’는 표현은 저자의 경험적 평가입니다.
원문에는 재설명 시간, 작업 성공률, 오류율 등을 비교한 측정 결과가 없습니다.[1]

실무 적용 시에는 ‘기억을 갖게 했다’는 인상보다 다음 항목을 확인해야 합니다.

• 새 세션에서도 필요한 문서를 실제로 찾아가는가?
• 현재 유효한 정책과 과거 기록을 구분하는가?
• 문서에 없는 내용을 추측하지 않고 확인을 요청하는가?

핵심 시사점: 맥락의 지속성은 문서를 보관하는 것만으로 확보되지 않습니다. 찾아 읽는 경로와 최신성 확인 방식까지 필요합니다.

 

2. 구조를 깎다 — 정보를 저장하지 말고, 정보를 찾는 방법을 저장하라

원문 핵심

처음에는 서비스 목록, 저장소, 운영 작업, 배포 절차를 한 파일에 모았지만, 파일이 500줄을 넘으면서 필요한 정보 하나를 찾기 위해 전체를 읽는 문제가 발생합니다. 저자는 진입 문서를 목차로 바꾸고 지식을 분리합니다.[1]

원문에서 가장 중요한 원칙은 다음 문장입니다.

“정보를 저장하는 게 아니라, 정보를 찾는 방법을 저장한다.”[1]

실제 디렉터리 구조는 다음 기준으로 나뉩니다.[1]

영역	원문 구성	구분 기준
진입점	CLAUDE.md	지식 탐색을 위한 목차
팀 지식	handbook/who, where, how	사람·팀, 환경·도구, 프로세스·컨벤션
서비스 지식	services/	서비스별 정책과 구현·운영 정보
서비스 공통 지식	services/_common/	여러 서비스에 공통으로 적용되는 내용
이력	history/	작업·결정·사고·하네스 개선 제안
실행 자산	repos/, scripts/	코드 저장소와 자동화 스크립트

서비스 내부는 다시 spec, internals, architecture, operations로 분리합니다.[1]

기술적 의미

① 진입점을 ‘백과사전’이 아닌 ‘라우팅 지도’로 만든다

CLAUDE.md에 모든 지식을 넣는 대신, 어떤 질문에 어떤 문서를 읽어야 하는지 안내합니다.

분석적으로 보면 이는 필요한 맥락을 단계적으로 읽게 하는 구조입니다. 다만 원문은 파일과 목차를 통한 탐색을 설명하며, 벡터 검색이나 검색엔진 기반 RAG를 구현했다고 말하지는 않습니다.

② 검색 구조보다 ‘새 지식의 배치 기준’이 중요하다

저자는 구조의 진짜 가치를 “정보가 어디에 있는가”보다 “새 정보를 어디에 쌓는가”를 명확히 하는 데 둡니다.[1]

이는 지식관리 관점에서 중요한 주장입니다. 저장 위치가 모호하면 다음 문제가 생길 수 있습니다.

• 같은 정책이 여러 문서에 중복됨
• 일부 문서만 수정되어 내용이 충돌함
• AI가 어느 문서를 우선해야 하는지 판단하지 못함

즉, 디렉터리 구조는 단순한 파일 정리가 아니라 지식 분류와 유지관리 규칙의 출발점입니다.

한계와 보완 의견

[보완 필요] 목차가 있다고 필요한 문서를 반드시 읽는 것은 아닙니다.

다음 사항은 추가 설계가 필요합니다.

• 작업 유형별 필수 참조 문서
• 문서 간 우선순위
• 공통 규칙과 서비스별 예외의 관계
• 문서 담당자와 최종 검토일
• 폐기·대체된 문서의 표시

또한 원문의 500줄은 해당 사례의 규모이지, 모든 하네스에 적용되는 분할 임계값은 아닙니다.[1] 파일 길이뿐 아니라 주제 응집도, 변경 빈도, 실제 사용 패턴을 기준으로 분리하는 것이 타당합니다.

핵심 시사점: 지식 구조의 목적은 파일 수를 늘리는 것이 아니라, 같은 사실의 기준 문서를 명확히 하고 필요한 맥락만 읽도록 만드는 것입니다.

 

3. 기록을 남기다 — 경험을 축적하되, 오답을 영구 지식으로 만들지 말라

원문 핵심

저자는 작업 결과만 남아 있고 그 이유가 사라지는 문제를 지적합니다. 이를 해결하기 위해 세 가지 기록과 하나의 개선 제안 영역을 둡니다.[1]

기록	보존하는 내용	업무상 가치
work-log/	어떤 작업을 어떻게 진행했는가	수행 방식과 업무 패턴 재사용
decisions/	어떤 결정이 왜 내려졌는가	판단 근거와 제약조건 보존
incidents/	어떤 실수가 있었는가	유사 위험의 재발 방지
harness-backlog/	AI가 제안한 하네스 개선 사항	검토 전 지식의 격리

저자는 작업 기록을 10건 쌓은 뒤 11번째 작업부터 기존 스타일에 맞게 수행하는 모습을 관찰했고, 사고 기록이 유사한 위험 상황에서 AI가 멈추는 데 도움을 주었다고 설명합니다.[1]

다만 여기에는 중요한 함정이 있습니다.

AI가 자신의 답변이 틀렸다는 사실을 모르면, 오답을 유용한 지식으로 판단해 하네스에 반영할 수 있다.[1]

이를 막기 위해 저자는 “AI가 제안하고, 반영은 내가 한다”는 원칙을 채택합니다.[1]

기술적 의미

① 결과뿐 아니라 ‘결정의 이유’를 외부화한다

작업 로그는 “무엇을 했는가”를, 결정 기록은 “왜 그렇게 했는가”를 보존합니다.

이 둘을 구분해야 이후 AI가 과거 행동을 무조건 반복하지 않고, 당시 조건과 현재 조건이 같은지 검토할 수 있습니다.

② 기억의 양보다 ‘기억의 신뢰성’이 중요하다

원문 도식은 다음 선순환을 보여줍니다.

기록 축적 → 하네스 업데이트 → AI 답변 품질 향상 → 추가 기록.[1]

하지만 본문은 이 흐름에 검증이 없으면 잘못된 정보가 반복적으로 강화될 수 있다고 경고합니다.[1]

따라서 본문의 통제 원칙을 반영한 운영 흐름은 다음과 같이 재구성할 수 있습니다.

업무 수행 → 개선 후보 기록 → 사람의 검토 → 승인된 내용 반영 → 후속 업무에서 확인

이는 본문을 종합한 분석적 재구성이며, 원문 도식에 사람의 승인 단계가 직접 그려져 있는 것은 아닙니다.

③ ‘학습’과 ‘외부 기억 활용’을 구분해야 한다

기록을 읽고 다음 업무에 활용하는 것은 이 사례에서 외부 지식의 재사용입니다. 원문은 모델 가중치가 갱신되거나 파인튜닝되었다고 설명하지 않습니다.

한계와 보완 의견

[확인 필요] ‘10건 이후 효과’는 일반적인 최소 학습량이 아닙니다.
업무 난이도, 기록 품질, 모델, 반복 실험 조건이 제시되지 않은 개인 관찰입니다.[1]

[보완 필요] 사람의 검토도 근거와 절차가 필요합니다.

원문의 백로그 예시는 date, time, title, type, service, source, status를 포함합니다.[1] 실무에서는 여기에 다음 항목을 추가하는 것이 유용합니다.

• 원문·코드·실행 결과 등 구체적 근거
• 제안자와 검토자
• 승인 또는 반려 이유
• 적용 범위와 유효 시점
• 기존 문서와의 충돌 여부
• 반영된 변경 이력

핵심 시사점: AI가 생산한 내용은 곧바로 조직 지식이 되는 것이 아니라, 검토해야 할 지식 후보로 취급해야 합니다.

 

4. 규칙을 세우다 — ‘하지 마’라는 지시에서 ‘할 수 없도록’ 하는 통제로

원문 핵심

저자는 “모든 작업은 반드시 확인을 받고 실행하라”는 규칙을 작성했지만, 복잡한 맥락에서 AI가 이를 무시해 사고가 발생했다고 설명합니다. 이후 통제를 세 단계로 강화합니다.[1]

단계	원문의 방식	의미
1층: 텍스트 규칙	“DB는 SELECT만 실행한다”	AI의 행동을 지시
2층: 구조적 강제	DB 접근을 특정 스크립트로 제한	실행 경로를 정형화
3층: 권한 차단	쓰기가 불가능한 계정 제공	실제 실행 능력을 제한

원문은 scripts/db-query.sh를 통해 쿼리를 전달하는 예시와, 쓰기 시도가 읽기 전용 설정 때문에 거부되는 MySQL 오류를 제시합니다.[1]

기술적 의미

이 챕터의 핵심은 AI가 지시를 잘 따르는가와 잘못된 지시를 실행할 수 있는가를 분리하는 데 있습니다.

• 텍스트 규칙은 행동을 유도합니다.
• 구조적 통제는 허용된 경로를 제한합니다.
• 권한 통제는 실제 수행 능력을 제한합니다.

원문도 규칙의 목적을 단순한 사용성 개선이 아니라, 실수가 발생했을 때 피해가 어디까지 갈 수 있는지 미리 제한하는 것으로 설명합니다.[1]

이는 글 전체에서 운영 안전성과 가장 직접적으로 연결되는 주장입니다.

중요한 기술적 주의점

① 스크립트 경유가 곧 강제 통제는 아니다

분석·권고: AI가 다른 DB 클라이언트, 직접 접속 경로, 스크립트 수정 권한을 갖고 있다면 “이 스크립트만 사용하라”는 지시는 우회될 수 있습니다.

따라서 구조적 강제로 인정하려면 다음을 확인해야 합니다.

• 우회 가능한 접속 경로가 차단되었는가?
• AI가 스크립트를 수정할 수 없는가?
• 접속 자격증명에 직접 접근할 수 없는가?
• 실행 대상과 입력이 검증되는가?

원문은 이 조건들의 상세 구현까지 제시하지 않습니다.[1]

② 예시 오류와 계정 권한을 구분해야 한다

원문 오류 메시지는 MySQL 서버의 --read-only 설정 때문에 해당 쓰기가 거부되었다고 말합니다.[1]

따라서 이 메시지만으로 해당 계정의 쓰기 권한 자체가 제거되었다고 확인할 수는 없습니다. 계정 권한 제한과 서버 읽기 전용 설정은 별도로 검증해야 합니다.

③ 읽기 전용이라고 모든 위험이 없어지는 것은 아니다

분석·권고: 데이터 변경이 금지되어도 민감정보 조회, 과도한 조회, 결과의 외부 전달 같은 위험은 남습니다.

따라서 읽기 전용 권한에 더해 접근 대상, 조회량, 실행 시간, 데이터 노출 범위를 제한할 필요가 있습니다.

실무 시사점

업무 지침은 AI에게 전달하고, 실행 권한은 AI의 판단과 독립적으로 제한해야 합니다.

감리·품질보증 관점에서는 “규칙 문서가 존재한다”보다 금지된 작업을 실제로 시도했을 때 차단되는지가 더 강한 검증 증거입니다.

 

5. 은총알은 없다 — 하네스는 설치하는 제품이 아니라 유지하는 업무 자산이다

원문 핵심

저자는 자동 구축 도구와 베스트 프랙티스 템플릿의 유용성을 인정하면서도, 완성된 하네스를 가져오는 것만으로 자신의 업무에 맞는 환경이 만들어지지는 않는다고 설명합니다.[1]

핵심 문장은 다음과 같습니다.

“하네스의 가치는 ‘무엇이 적혀 있는가’보다 ‘왜 이렇게 적혀 있는가’에 있기 때문이다.”[1]

디렉터리와 규칙에는 팀이 겪은 시행착오가 반영되어 있고, 업무·배포·논의가 진행되면서 계속 수정해야 한다는 주장입니다.[1]

기술적 의미

하네스는 다음 세 요소를 연결하는 자산으로 해석할 수 있습니다.

1. 업무 지식: 무엇을 운영하고 어떤 기준을 적용하는가

1. 판단 근거: 왜 그 구조와 규칙을 선택했는가

1. 운영 통제: 무엇을 허용하고 무엇을 제한하는가

따라서 하네스 품질은 문서의 정교함만이 아니라 현재 업무와 얼마나 일치하는지에 달려 있습니다.

한계와 보완 의견

[보완 필요] ‘직접 깎아야 한다’를 개인 의존으로 해석해서는 안 됩니다.

원문은 개인 경험담이지만, 조직 적용에서는 작성자의 머릿속에만 ‘왜’가 남아 있으면 인수인계가 어려워집니다.

따라서 다음을 조직 자산으로 남기는 것이 필요합니다.

• 규칙별 도입 배경과 관련 사고
• 변경 승인자와 관리 책임자
• 적용 범위와 예외
• 검토 주기
• 변경 후 검증 방법

또한 표준화와 맞춤화는 대립하지 않습니다. 분석적으로는 공통 안전장치와 기록 형식은 표준화하고, 서비스별 지식과 예외는 맞춤화하는 접근이 적절합니다.

핵심 시사점: 재사용해야 할 것은 완성된 내용만이 아니라, 구조·검토 절차·통제 방식입니다.

 

6. 맺으며 — 모델 성능과 업무 활용 능력은 다르다

원문 핵심

저자는 다음 문장으로 글을 마무리합니다.

“AI 도구의 성능은 ‘모델’이 결정하지만, 활용의 깊이는 ‘맥락’이 결정한다.”[1]

그리고 처음부터 완벽한 체계를 구축할 필요 없이 파일 하나에서 시작해, 업무와 실수를 통해 개선할 수 있다고 제안합니다.[1]

분석

이 문장은 글의 취지를 잘 압축하지만, 엄밀한 기술적 법칙보다는 실무적 메시지로 읽는 것이 적절합니다.

분석적으로 실제 업무 결과에는 다음이 함께 영향을 미칩니다.

• 모델의 추론·생성 능력
• 제공된 맥락의 정확성과 최신성
• 적절한 도구와 실행 환경
• 권한과 승인 체계
• 결과 검증과 피드백

따라서 좋은 맥락이 모델의 모든 한계를 해결하지는 않으며, 고성능 모델도 잘못된 맥락과 과도한 권한 아래에서는 위험한 결과를 만들 수 있습니다.

핵심 시사점: 작게 시작하는 것은 타당하지만, 운영 시스템 접근이 포함된다면 최소 권한과 검증 절차는 초기부터 마련해야 합니다.

 

7. 종합 평가 — 이 글에서 받아들일 것과 추가 검증할 것

구분	평가
가장 설득력 있는 주장	맥락을 구조화하고, 검증되지 않은 기록의 자동 반영을 막으며, 실제 권한으로 피해 범위를 제한해야 한다는 점
경험적으로 제시된 효과	되묻기 감소, 기존 업무 스타일 재사용, 유사 위험에서 멈추는 행동
입증되지 않은 부분	생산성 향상률, 오류 감소율, 최적 문서 크기, 필요한 기록 수, 다른 팀·모델에서도 동일한 효과가 나는지
조직 적용 시 보완점	지식 책임자·최신성·승인 이력, 우회 경로 차단, 권한 검증, 변경 후 평가
적용 방식	디렉터리를 그대로 복제하기보다, 지식 탐색·기록 승인·실행 제한의 원칙을 업무에 맞게 구현

원문에 정량 지표가 없으므로, 조직 도입 시에는 다음을 추가 평가 지표로 제안할 수 있습니다.

평가 영역	확인할 지표
맥락 탐색	필수 문서 참조 여부, 잘못된 문서 선택 건수
업무 효율	[설명] 재설명 시간, 완료 시간, 사람의 수정 시간
지식 신뢰성	[출처] 없는 기록, 오래된 정책 사용, 문서 간 충돌
실행 안전성	승인 누락, 금지 작업 차단, 우회 경로 존재 여부
지속 개선	승인된 변경 후 유사 오류 재발 여부

최종 해석

이 글은 하네스를 ‘더 많은 지식을 넣는 장치’가 아니라, ‘필요한 지식을 찾고, 검증된 경험만 반영하며, 잘못된 실행의 피해를 제한하는 업무 운영 체계’로 바라보게 한다는 데 가치가 있습니다.

감리 관점에서 이를 적용한다면 다음 세 질문으로 압축할 수 있습니다.

1. AI가 참조한 지식은 현재 유효하고 추적 가능한가?

1. AI가 제안한 기록과 규칙 변경은 검토·승인되었는가?

1. AI가 규칙을 어겨도 실제 실행 권한이 피해를 제한하는가?

출처

[1] https://meetup.nhncloud.com/posts/423 — 나는 하네스 깎는 노인이 되었다 시리즈 1: 은총알은 없다