🏆 AI스터디 23기 4주차 베스트 사례 큐레이션 - 개발&에이전트

📚 23기 에이전트하네스

✍️ verifier 기준으로 나눈 세 Skill을 하나의 현금흐름 분석 하네스로 이은 3주차 실습(에이전트 하네스 3주차)

자연어회계처리

하려던 것 📝

• 나뉜 현금흐름 분석 Skill을 하나의 워크플로우로 연결하여 자동 판정 신뢰도를 높인 사례

• 2주차에 분리했던 일반 현금화 추적과 업무별 소멸 예외 판정을 하나의 워크플로우 하네스(Trigger → Context → Route → Gate → Proof → Verdict → Approval/Repair)로 연결하여 실행 흐름을 명확히 하고자 함.

• 잘 나뉜 실행 조각과 연결 코드에 가까웠던 기존 시스템을 개선하여 언제 시작하고 어떤 입력을 믿으며 어떤 결과를 자동 완료하면 안 되는지, 실패 시 어디를 고쳐야 하는지가 하나의 실행 계약으로 묶여 있지 않던 문제를 해결하고자 함.

• 나눈 Skill 조각들을 어떤 조건과 순서로 움직이고 무엇을 보고 끝났다고 말할지, 실패 시 전체를 다시 만들지 않고 실패 소유자만 찾아 고치며, 자동 판정과 사람 검토의 경계를 명시적으로 남기고자 함.

활용한 툴 ⚒️

• Hermes Agent v0.20.0: workflow 실행 및 관리

• Python 3.11 표준 라이브러리: 코드 작성 및 실행 환경 제공

• `unittest`: 코드 테스트 및 회귀 테스트 수행

• W2에서 만든 learner-owned working copy: 작업 환경 및 코드 베이스

• JSON 실행 영수증과 회귀 테스트: 실행 결과 기록 및 검증

진행 세부 내용 🔍

• 1️⃣ 가장 작은 정상 실행 구성함

• 시도한 방법과 접근 방식: 비식별 분개 5행을 실제 working copy 하네스에 입력하여 정상 흐름을 실행함.

• 사용한 프롬프트나 코드: 하네스 설계 계약에 따라 `Trigger → Context → 일반 추적 → 예외 규칙 → 최종 Gate → 승인/완료` 흐름을 따름. JSON 실행 영수증을 기록하도록 구성함.

• 얻은 결과나 피드백: input_target_amount 600.0에 대해 cash_classified 100.0, exception_extinguished 200.0, pure_noncash 300.0으로 분류되어 금액 보존이 PASS되었고, Criteria 4항목(금액 보존, 중복 소유 없음, 사업장 누락 예외 자동 소멸 안 함, 사업장 누락 예외 human_review)을 모두 충족하여 `verdict: PASS`, `committed: true`, `approval: not_required` 결과를 얻음.

• 2️⃣ 의도적으로 실패하는 입력으로 자동 소멸 문제 확인 및 검증함

• 시도한 방법과 접근 방식: 정상 실행 후 Criteria를 고정한 상태에서 사업장 식별자가 빠진 시간주차비 원행과 반제행(총 250.0)을 의도적으로 입력함.

• 발생한 문제와 해결 방법: 기대 동작은 `human_review`였으나, 수리 전 예외 규칙이 빈 문자열을 같은 사업장으로 취급하여 250.0이 `exception_extinguished`로 자동 소멸되는 문제가 발생함. 이는 금액 보존은 true였지만 업무 판정은 틀렸음을 의미함.

• 얻은 결과나 피드백: `gate`의 `missing_business_unit_never_extinguished`와 `known_exception_missing_unit_goes_to_human_review` 항목이 `false`로 판정되어 `verdict: FAIL`, `committed: false` 결과가 나옴. 최종 verifier가 commit을 막아 잘못된 판정이 시스템에 반영되는 것을 방지함.

• 3️⃣ 발생한 문제점 확인 및 최소 범위로 수정함

• 발생한 문제와 해결 방법: 첫 번째 막힘은 대상 로직이 아닌 회귀 테스트 파일의 루트 경로 계산 오류였으며, 이를 수정하여 정상 테스트는 통과하고 사업장 누락 테스트만 예상대로 실패함을 확인했음. 실패 소유자를 `journal-extinction-exception-rules`로 확인한 후, 수리 전 working copy를 백업 및 복원 리허설을 수행하여 복구 가능성을 검증함.

• 시도한 방법과 접근 방식: `journal-extinction-exception-rules` 파일에 두 가지 예외 규칙을 추가함: 1) 사업장 식별자가 빈 값이면 두 행을 같은 사업장으로 비교하지 않음. 2) 시간주차비·내국신용장 대상의 사업장 식별자가 빠졌다면 자동 소멸 대신 `human_review`로 반환함.

• 사용한 프롬프트나 코드: "Tree를 다시 나누지 말고, Trigger → Context → Route → Gate → Proof → Verdict가 있는 가장 단순한 workflow 하네스로 연결해줘..." 프롬프트에 따라 작업함. Umbrella, 일반 경로 추적기, 정상 입력, 실패 입력, Criteria는 변경하지 않고 최소한의 수정만 진행함.

• 얻은 결과나 피드백: 백업 및 복원 리허설이 `PASS`되었고, 단 하나의 파일만 수정함.

• 4️⃣ 같은 기준과 입력으로 수정된 하네스를 재평가함

• 시도한 방법과 접근 방식: 수리 전과 동일한 사업장 누락 250.0 입력을 다시 실행하여 변경 사항을 검증함.

• 얻은 결과나 피드백: 자동 소멸 250.0이 `human_review` 250.0으로 이동했으며, 같은 Criteria 네 항목을 모두 통과하여 `gate_verdict: PASS`가 나옴. 사람 승인이 필요하므로 최종 실행은 `HOLD` 상태로 멈추고 `approval: required`로 표시됨.

• 사용한 프롬프트나 코드: 수정된 `journal-extinction-exception-rules`를 적용한 하네스를 사용함.

• 얻은 결과나 피드백: 새 하네스 테스트(정상 경로, 사업장 누락 `human_review` 모두 `ok`)와 기존 W2 동작 회귀 테스트(4개 테스트 모두 `ok`)가 모두 통과됨을 확인하여 수리의 유효성을 입증함.

📚 23기 반려에이전트

✍️ 드라마치료 현장의 배경음을 버튼 하나로 칸반 AI 워커팀과 만든 「장면소리」 MVP

달감휘

하려던 것 📝

• 드라마치료 현장용 음향을 즉시 재생하도록 지원한 사례

• 드라마치료 및 사이코드라마 현장에서 공간 분위기, 장면 전환, 정서 고조와 이완에 필요한 음향 효과가 중요함을 인지함.

• 진행 중 적절한 음향 파일을 찾거나 유튜브를 오가는 과정이 장면의 흐름과 참여자의 몰입을 끊을 수 있는 문제 해결을 시도함.

• 진행자가 장면을 놓치지 않으면서 필요한 소리를 버튼 하나로 즉시 재생할 수 있는 오프라인 Windows 사운드 큐 프로그램 개발을 목표로 함.

• 저작권 문제 없는 기본 음향팩을 포함하고, 설치 및 인터넷 연결 없이 USB 포터블로 사용할 수 있는 현장용 도구 제작을 추진함.

활용한 툴 ⚒️

• Hermes (AI 워커팀 플랫폼): AI 워커 프로필 분리 및 운영, 칸반 작업 관리

• worker-scout: 현장 요구, 유사 프로그램, 기술 구조, 개인정보·저작권·청력 안전 기준 조사에 활용함.

• worker-maker: Electron·React 앱 구현, 테스트 작성, Windows 실행 파일 제작 및 패키징에 활용함.

• worker-review: 구현 결과와 산출물의 기능·안전·화면 독립 검수에 활용함.

• 루너 (총괄 기획 AI 에이전트): 전체 목표의 작업 분해·배정, 워커 간 결과 통합, 문제 발생 시 개입, 최종 실행·재검증에 활용함.

진행 세부 내용 🔍

• 1️⃣ 칸반 AI 워커팀 구성 및 역할 분리

• 시도한 방법: 일상 대화용 에이전트와 별개로 `worker-scout`, `worker-maker`, `worker-review` 세 가지 칸반 전용 작업 프로필을 새로 만들고, `루너`를 총괄 기획 및 관리 역할로 정의하여 AI 워커팀을 구성함.

• 사용 목적: 한 에이전트가 모든 작업을 수행하며 발생할 수 있는 오류 반복 및 긴 대화 내 단계 파악 어려움 문제를 해결하고, 각 워커의 전문성을 활용하여 효율적인 협업을 가능하게 함.

• 얻은 결과: 조사, 구현, 독립 검수라는 명확한 역할 분리 기반을 마련하여 프로젝트를 체계적으로 진행할 수 있게 함.

• 2️⃣ 현장 요구 및 기술 명세 조사

• 시도한 방법: `worker-scout`에게 `[장면소리 MVP] 현장 요구·기술·안전 명세 조사` 과제를 배정하여 드라마치료 현장의 사용 흐름과 기술 및 안전 기준을 조사하게 함.

• 내용: 큰 한국어 버튼의 사운드 큐 보드, 여러 음원의 동시 재생, 반복 및 페이드인·아웃, 전체 즉시 정지, 로컬 파일 저장 및 재연결, 자동재생 금지, 개인정보 비저장 구조, Electron의 파일 접근 및 보안 경계, 저작권 원칙 등을 포함함.

• 얻은 결과: 구현 워커가 바로 사용할 수 있는 요구사항과 수용 기준이 담긴 명세 문서를 산출하여 개발의 방향성을 명확히 함.

• 3️⃣ Electron·React 기반 사운드 큐 앱 구현 및 패키징

• 시도한 방법: `worker-maker`에게 `[장면소리 MVP] Electron·React 앱 구현과 Windows 패키징` 과제를 배정하여 조사 결과를 바탕으로 실제 프로그램을 구현하게 함.

• 내용: Electron·React·Vite 기반 앱 개발, Web Audio API 기반 재생 엔진, 음원 추가·재생·정지·반복, 개별 및 마스터 음량 조절, 페이드인·아웃, 다중 동시 재생, 전체 즉시 정지, 보드 생성·관리, 설정 저장 및 복원, Windows 포터블 실행 파일 제작 등을 포함함.

• 얻은 결과: 프로그램 구현은 물론 자동 테스트, 프로덕션 빌드, 실제 Windows 실행 파일 생성까지 완료를 조건으로 두어 최종 산출물인 `장면소리` 프로그램을 완성함.

• 4️⃣ 독립 검수 및 핵심 문제 해결

• 시도한 방법: `worker-review`에게 `[장면소리 MVP] 독립 기능·안전·시각 검수` 과제를 배정하여 구현 결과물을 독립적으로 검토하도록 함. 총괄자(`루너`)가 검수 과정에서 발생한 문제에 직접 개입하여 해결함.

• 발생한 문제: 저장된 보드 음원 경로 재생 불가, 파일 재연결 버튼 부재, 재생 상태 화면 미반영, 재생 중 음량 변경 미적용, 불필요한 메모리 데이터 전달, 페이드아웃 시간 고정, 빌드된 테스트 파일 수집으로 인한 테스트 실패, 패키징 후 화면이 흰색으로만 나타나는 문제 등 8가지 주요 오류가 발생함. 특히 흰 화면 문제는 개발 환경에서는 나타나지 않고 실제 Windows 실행 파일에서만 발생하는 어려움이 있었음.

• 해결 방법: `루너`가 반복 생성된 중복 과제를 중단하고 실제 소스와 산출물을 직접 확인하여 오류를 재현함. 테스트를 추가한 뒤 수정하고 프로그램을 재빌드하며 Windows 실행 화면 및 USB 포터블 복사본까지 최종 재검증하는 과정을 거침. 흰 화면 문제는 회귀 테스트를 만들고 Vite의 자산 경로를 수정하여 해결함.

• 얻은 결과: 발견된 문제들을 성공적으로 수정하여 프로그램의 안정성과 기능성을 확보하고, Windows에서 정상적으로 실행되는 최종 결과물을 얻음.

• 5️⃣ 기본 음향팩 제작 및 USB 포터블 환경 구성

• 시도한 방법: 프로그램의 즉시 현장 활용을 위해 저작권 문제가 없는 35개의 기본 음향팩(환경음 8개, 효과음 13개, 배경음 6개, 장면신호 4개, 정서질감 4개)을 직접 합성하거나 사용권을 확인한 로컬 파일로 제작하고 분류 및 정규화함.

• 내용: 정서적인 소리는 선율이 강한 음악보다 환경음, 드론, 단순한 질감 위주로 구성하여 참여자의 감정을 특정 방향으로 지나치게 유도하지 않도록 판단함.

• 얻은 결과: 프로그램과 함께 USB 포터블 형태로 제공되는 `장면소리 0.2.3 Portable`을 완성하여 다른 PC에서도 설치 없이 즉시 사용할 수 있게 함. USB 드라이브 문자가 변경되어도 저장된 경로가 현재 USB 위치를 기준으로 자동 복구되도록 보완함.

📚 23기 내업무에이전트

✍️ AI 인격 두 개가 한 파일에 살면 생기는 일- 감정담당과 건강담당

뽀짝미르사

하려던 것 📝

• AI 비서의 규칙 파일 충돌 해결 및 개념 카드 적용을 통해 감정 AI를 고도화한 사례

• 감정 담당 AI(나나)와 대화 중 건강 담당 AI(미나)의 기록 파일이 수정되는 오작동을 발견함.

• 두 AI 인격의 규칙이 하나의 성격 설명서 파일(SOUL.md)에 통합되어 있어 규칙 충돌이 발생함을 확인하고, 설명서 구조 전체를 점검하고자 함.

• AI 인격 간의 규칙 충돌 및 오작동 문제를 해결하고, "위로만 하고 알맹이가 없다"는 지적을 받은 감정 AI의 응답을 개선하여 실질적인 도움을 주는 답변을 생성하도록 개선하고자 함.

활용한 툴 ⚒️

• Claude Code (Sonnet 5): AI 비서의 규칙 작성 및 수정, 파일 분리, 개념 카드 제작

• 헤르메스(Hermes): 텔레그램 기반 AI 비서 플랫폼으로 대화 테스트 및 기능 구현

• 헤르메스 그록(Grok) 두뇌: AI의 판단 및 처리 로직 구동

• git: 규칙 파일 변경 기록 확인 및 관리

진행 세부 내용 🔍

• 1️⃣ 문제 진단

- 감정 AI가 건강 파일을 수정하는 실제 오작동, "애매한 건 다 질문"과 "건강 파트는 최대 3개까지만 묻는다"는 모순 규칙의 동시 활성화 등 6가지 문제점을 진단함. - 동일 규칙의 5곳 반복, 미나 AI(일정+인맥+건강+옷장)에 규칙 분량 쏠림(74%), 폐기된 옛 규칙의 잔존, 규칙 번호 꼬임 등을 파악함.

• 2️⃣ "넘기기" 대신 "역할 나누기" 판단

- 건강 문제를 감정 AI에 통째로 넘기는 것이 성격 충돌(명확한 판정 vs 공감) 및 응급 상황 시 위험 가능성으로 불가함을 판단함. - 대신 "말하는 담당"(감정 AI)과 "기록하는 담당"(건강 AI)으로 역할을 나누는 방식을 채택하여 충돌 없이 한 상황을 처리하도록 함. - 단, 응급 신호가 보이면 건강 AI가 즉시 개입하는 2가지 예외 규칙은 유지함.

• 3️⃣ 파일 쪼개기

- 옷장 규칙(79줄), 건강 규칙(113줄), 일정·인맥 규칙(44줄), 감정 규칙(46줄)을 각각 `mina_wardrobe.md`, `mina_health.md`, `mina_schedule.md`, `nana_emotion.md`로 4단계에 걸쳐 분리함. - 건강 규칙 분리 시 모순 규칙을 삭제하고 "감정 겹칠 때 담당 구분" 규칙을 신설했으며, 감정 규칙 분리 시 번호 꼬임을 정리하고 옛 규칙 문장을 별도 보관함. - 매 단계마다 실제 텔레그램 대화로 테스트를 진행했고, 성격 설명서(SOUL.md) 용량을 14,535자에서 4,719자로 68% 줄이는 결과를 얻음.

• 4️⃣ 형식은 성공, 내용은 실패

- 감정 AI가 3번 대화 후 정확히 화제를 전환하는 형식적 기능은 잘 작동함을 확인했지만, 전환 후 말 5개 중 4개가 프레임이론과 무관한 일반적인 위로임을 확인함. - "대화가 안 맞으면 힘 빠지죠" 같은 상식적인 위로에 그쳐 내용 면에서 실패했음을 지적받음.

• 5️⃣ 원인 추적 — 로그를 직접 열어봄

- 화면에는 "🔍 검색 중"이라고 떴으나, 로그 파일(`agent.log`)을 직접 열어보니 윈도우 경로를 리눅스 방식으로 잘못 변환하여 검색이 모두 실패하고 있었음을 발견함. - AI 규칙에 "필요한 파일을 검색해서 찾아라" 대신 정확한 전체 경로를 직접 적어줘야 함을 깨달음.

• 6️⃣ 개념 카드 제작

- 말투 파일만으로는 부족하다고 판단하여 프레임이론의 핵심 개념 7개를 사진 자료와 정리본 문서에서 추출함. - "[언제 쓰나] → [개념] → [할 말 예시]" 구조의 카드 파일(`nana_frame_cards.md`)을 제작함. - 감정 AI 규칙에 이 카드 파일을 반드시 읽고, 하나를 골라 사용하도록 명시하여 내용을 보강함.

• 7️⃣ 2차 테스트 — 카드는 쓰는데 "그냥 위로 같다"

- 개념 카드가 실제로 읽히고 쓰이는 것까지는 확인되었으나, 여전히 "일반적인 위로 같다"는 피드백을 받음. - 개념 이름 미사용, 같은 카드를 3턴 연속 반복, 카드 예시 문장을 거의 그대로 베껴 쓰기, "괜찮다"로만 끝나는 문제, 구체적인 상황과 연결되지 않아 카드가 헛도는 5가지 원인을 정리함.

• 8️⃣ 5가지 보강 후 3차 테스트 — 성공

- 이전에 파악된 5가지 문제점을 모두 규칙에 추가하여 보강한 뒤 다시 테스트를 진행함. - 사용자의 "유튜브 영상을 볼까, 지피터스 방송을 볼까 고민된다"는 고민에 감정 AI가 프레임이론 기반의 구체적이고 심층적인 답변을 제시하며 긍정적인 반응(❤️)을 얻음. - 매번 다른 카드(3→2→4)를 사용하고, "괜찮다"로 끝내지 않고 다음 행동까지 짚어주는 개선된 응답 패턴을 확인함.

📚 23기 AI결과물검수

✍️ 하네스 다이어트

박태진

하려던 것 📝

• 법인세 신고서식과 감사보고서의 특수관계자 거래를 AI로 대조하는 스킬을 개발한 사례

• 사람이 며칠씩 걸리던 특수관계자 거래 대조 작업을 AI가 자동화하여, 확실한 건 자동으로 확정하고 애매한 것만 '확인필요'로 남기는 도구를 만드는 것을 목표로 함

• '틀린 확정 0'을 원칙으로 하여, AI가 잘못된 판단을 내리지 않도록 높은 신뢰성을 확보하고자 함

• 사내 AI 에이전트 실행 환경에서 안정적으로 작동하는 대사 로직을 구현하고, 이를 위한 검증 절차를 고도화하는 것을 목적으로 함

활용한 툴 ⚒️

• Claude Code: 코드 작성 및 구현을 담당함

• Codex: 코드 리뷰 및 검토를 담당하며, 검수 기준 설계에도 활용함

• 사내 AI 에이전트 실행 환경: 엑셀 애드인 위에서 최종적으로 코드를 실행하고 대사 작업을 수행함

진행 세부 내용 🔍

• 1️⃣ 검증 방식 개선

• 기존 '무거운' 검증 방식(실행 명령과 출력 원문, 파일 해시와 수정시각 등 증거 요구)으로 인해 Claude Code에만 구현 작업이 몰리는 문제를 해결하고자 함

• AI 역할 분담을 '리뷰만'에서 '라운드마다 사람이 구현할 AI를 정하고, 구현하지 않은 AI가 리뷰'하는 방식으로 변경하여, 구현자와 승인자를 분리하는 검증의 본질은 유지하되 역할을 유연하게 만듦

• 이로 인해 Claude Code와 Codex 사이에서 구현 작업이 효율적으로 분배됨

• 2️⃣ 검수 기준 설계 및 문제 해결

• 사내 에이전트를 돌려보니, 똑같은 칸과 물음에도 실행할 때마다 답이 흔들리는(판단 불일치) 문제가 발생함을 확인함

• 원인을 분석한 결과, 자동으로 확정하려면 '그 숫자가 원래 금액이 적히는 칸 위치에 있는가'와 'AI에게 물어봤을 때 맞다는 답을 받았는가' 두 조건이 필요하지만, AI에게 판단에 필요한 정보(칸이 속한 표 제목)가 질문 문장에 아예 안 들어 있음을 발견함

• AI 실력 문제가 아닌 판단 재료 부족 문제임을 파악하고, '사람이나 AI 판단이 굳이 필요 없는 자리는 아예 정해진 규칙(코드)으로 대신 처리'하는 방향으로 새 규칙 아홉 개를 설계함

• 새 규칙 설계는 Codex가 만들고 Claude Code가 검토하는 방식으로 진행되었으나, 규칙 하나를 통과시킬 때마다 '이 규칙이 정말 안전한지 증명하라'(예: 681건 자료를 전부 열어 사람 손으로 확인)는 요구가 붙어 쟁점이 늘어나고 라운드가 길어지는 문제가 발생함

• 3️⃣ 검수 기준 설계 중 테스트 환경 문제 해결

• AI가 답한 내용을 정해진 형식으로 저장하는 프로그램'을 검수하는 과정에서, 저장한 내용이 형식에 맞게 잘 들어가는지, 저장 위치가 규칙대로 '프로그램 폴더 바깥'에 있는지 확인해야 함을 인지함

• 실제로 쌓여 있던 답 95개를 넣어 하나도 안 빠지고 저장되는지 자동으로 확인하는 테스트를 만들고, '저장 위치가 폴더 안쪽이면 바로 에러'를 내도록 테스트에 포함함

• 테스트 실행 중, 테스트 컴퓨터 환경 자체가 테스트용 임시 폴더를 프로그램 폴더 안쪽 경로로 잡고 있어, 저장 위치 코드는 멀쩡한데도 '안쪽에 저장했다'는 거짓 경보가 뜰 뻔했음을 발견함

• 제품 코드 문제가 아닌 테스트 방식의 문제임을 확인하고, 진짜 폴더 대신 테스트 전용으로 만든 가짜 폴더를 기준으로 검사하도록 테스트를 고쳤으며, 빠뜨렸던 경우(폴더 자기 자신 지정, 아예 지정 안 한 경우) 두 가지를 테스트에 추가함

• 4️⃣ 라운드 단축을 위한 검증 로직 개선

• 늘어나는 쟁점과 라운드 반려 문제를 해결하고자 사람이 직접 조건을 좁히는 방식으로 개선함

• '콤마 없는 숫자를 금액으로 볼 것인가'에 대한 판단 조건을 '위치 조건 + AI 판단'에서 '위치 조건 + 표에 적힌 합계와 실제로 더해보면 정확히 맞아떨어지는가'로 좁혀 AI 판단 단계를 생략하고 산수로만 확인하도록 함

• 다른 AI에게 리뷰를 보낼 때, 작업 상황 문서 네 개 중 하나라도 최신 내용이 아니면 라운드 전체가 반려되는 일이 세 번 반복되자, 보내기 직전에 네 개 문서가 서로 어긋나는지 자동으로 확인하는 검사를 만들고 이를 통과한 뒤에만 보내도록 바꿈

• 그 결과, 판단 쟁점 하나가 바로 정리되었고 라운드 반려 횟수를 줄이는 데 기여함

• 5️⃣ 병렬 처리 검증 및 성능 개선

• 회사별 대사 판정을 하나씩 순서대로 돌리던 방식에서 여러 개를 동시에 돌리는 병렬 방식으로 전환하여 속도 향상을 시도함

• 병렬 처리 시 '순서를 바꿔도 결과가 정말 하나도 안 바뀌는가'를 확인하기 위해 세 가지 방법을 사용하여 검수함: ① 동시 작업 간 파일 덮어쓰기 방지를 위한 전용 임시 폴더 사용 및 외부 변경 확인, ② 병렬 처리 전후 결과 파일 개수와 순차 처리 시 결과 비교, ③ 순차 처리 결과와 병렬 처리 결과 111건 전부를 파일 내용까지 비교함

• 검수 중 첫 번째 검사(전용 폴더 확인)에서 신고되지 않은 다른 작업 하나가 정해진 폴더 밖 파일을 건드리고 있었음을 발견하고 문제를 수정함

• 문제 해결 후 세 검사 모두 통과했으며, 실행 시간은 36분에서 18분으로 50% 단축됨. 다른 사내 에이전트도 열 번 만에 로컬에서 미리 확정해 둔 값과 금액 차이 0건까지 스스로 도달했음을 확인했으며, 길어지던 규칙 아홉 개 설계 승인 건은 쟁점을 좁힌 뒤 당일 안에 승인까지 끝남

📚 23기 스마트홈AI

✍️ 시중에 팔아도 안 부끄러울(?) 음성 인식 고양이 급식기 완성기

윤누리

하려던 것 📝

• 3D 프린팅으로 제작된 AI 음성인식 반려동물 급식기를 개선 및 완성한 사례

• 검볼머신 개조를 통해 간식 배출 데모까지 성공하였으나, 사료가 새는 문제 해결이 필요했음.

• 3D 프린팅 도안(Munch-E)을 바탕으로 부품을 조립하고 정밀하게 간식을 배출하도록 하는 것이 목적이었음.

• AI 음성인식 기능을 고도화하고 디스플레이 및 사운드 기능을 추가하여 사용성을 개선하고자 했음.

• 예상치 못한 하드웨어 및 소프트웨어 문제를 해결하며 프로젝트를 완성하는 것이 목표였음.

활용한 툴 ⚒️

• Claude: 부품 명칭 식별 및 이미지에 명칭 표시, 오거 작동 원리 설명 및 트릿 걸림 문제 해결 아이디어 제시, 모터 배선 해결 방법 제시, 디스플레이 화면 문제(색 반전, 뿌옇게 나옴) 원인 분석 및 해결 코드 제공, 마이크 배선 오류 진단, 음성인식 병목 구간 분석 및 해결 방안 제시, 인식률 개선을 위한 단어 사전 활용 방안 제시, 보드 손상 시 대응 전략 제시, 화면 지연 개선 아이디어 제시, 효과음 후보 생성 및 맥에서 미리 듣기 지원, 스피커 사용 제약 사항 설명, 액정 파손 시 임시방편 제시.

진행 세부 내용 🔍

1️⃣ 부품 이름표 부착으로 조립 효율화함 - 3D 프린팅 출력물 9개를 수령했으나, 각 부품의 명칭을 몰라 조립 설명서 이해에 어려움을 겪었음. - Claude에게 부품 사진을 보여주며 명칭을 알려달라고 요청함. - Claude가 텍스트로 명칭을 알려주었으나 여전히 헷갈려, 다시 사진 위에 번호와 이름, 리더선을 그려서 새 이미지로 만들어 달라고 요청함. - Claude가 생성해 준 이미지로 부품을 쉽게 식별하며 조립을 진행할 수 있었고, 조립 내내 이를 활용하여 대화하며 진행함.

2️⃣ 오거의 간식 배출 방식 이해 및 개선함 - 조립 후 트릿을 넣고 손으로 돌렸을 때 간식이 시원하게 나오지 않는 문제에 직면함. - Claude에게 스크류가 제대로 작동하지 않는 것 같다고 문의함. - Claude는 오거가 한 바퀴에 나선 한 칸만큼만 밀어내는 장치이므로, 1~3개의 트릿을 정밀하게 주는 것이 목표라면 현재의 배출 방식이 정상이라고 설명해 줌. - 트릿을 조금만 넣으면 바닥에 깔려 나선에 닿지 않아 배출되지 않는 문제가 발생함. - Claude에게 바닥에 박스 등으로 틈 높이를 줄이는 아이디어를 제시했고, Claude는 상용 급식기가 경사면인 이유를 설명하며 정석적인 방법이라고 답변함. - 페트병을 잘라 바닥에 붙여 경사면을 만들어 간식 배출 문제를 임시 해결했으며, 이는 효과가 있었지만 더 손봐야 할 과제로 남음. - 트릿이 입구에서 서로 얽혀 아치를 만드는 '브리징' 현상으로 배출량이 0알에서 6알까지 편차가 큰 문제가 발생했으며, 이는 아직 해결하지 못함.

3️⃣ 음성 인식을 통한 간식 배출 기능 구현함 - 배선을 정리하고 음성 인식 기능을 추가하는 과정에서, 모터가 1초 돌다 멈추는 문제를 겪음. - 원인은 모터에 물린 선이 조립 중 빠진 것이었으며, 악어클립으로는 진동에 자꾸 빠지는 문제가 발생함. - Claude는 모터 단자의 구멍에 전선 피복을 벗겨 꿰고 5~6바퀴 감으라고 제안했고, 이 방법으로 납땜 없이 진동에 빠지지 않게 연결하는 데 성공함. - "로나 트릿"이라고 말하면 새 기계에서도 간식이 성공적으로 배출되었으며, 검볼머신에 이어 두 번째로 말을 알아듣는 기계가 됨.

4️⃣ 디스플레이 기능 개발 및 문제 해결함 - 이전에 터치가 안 되는 2.8인치 화면을 활용하여 로나 얼굴과 급여 횟수, 시각을 띄우는 디스플레이를 만들기로 함. - 첫 화면: 색이 반전되고, 화면이 뿌옇게 나타남: 화면에 귀신처럼 색이 반전되어 나타났고, Claude의 도움으로 화면 색을 뒤집는 설정 한 줄이 빠졌음을 찾아 해결함. - 색 반전 문제를 해결한 후 전체 화면이 뿌옇게 보이는 문제가 발생했고, 보호 필름 문제가 아님을 확인 후 Claude와 함께 원인을 분석함. - Claude는 화면을 그리는 라이브러리가 선명도 관련 설정을 보내지 않아 화면 기본값이 뿌옇게 적용된 것이라고 진단했으며, 데이터시트를 통해 직접 값을 써넣어 선명도를 개선함. - 캘린더 화면은 목업부터: "이번 주에 얼마나 줬는지"를 확인하는 캘린더 화면을 구현할 때, 실제 화면에 굽고 확인하는 데 3분씩 걸려 웹 목업을 먼저 제작하여 브라우저로 비교함. - 320x240 실제 크기의 목업 시안 3개를 나란히 비교하여 월간·주간 화면 두 개를 선택함. - 목업에서 CSS로 준 둥근 모서리가 실제 코드에는 반영되지 않아, 목업은 방향성만 잡는 데 사용되고 결국 실물을 봐야 완료됨을 경험함. - 마이크는 배선 정보가 정반대였음: 급식기 앞에서 말할 수 있도록 마이크를 연결했으나, 마이크 값이 계속 0으로 나타나는 문제가 발생함. - Claude는 마이크 대신 스피커부터 테스트하여 회로의 활성 여부를 확인하는 접근 방식을 제안함. - Claude는 배선 후보 24가지에 대해 각각 다른 음높이로 소리를 내게 하고 맥북 마이크로 녹음하여 주파수를 분석, 정답을 역산하는 방식으로 배선 문제를 해결함. - 보드 제조사 정보를 통해 알고 있던 마이크 배선이 실제로는 입력과 출력이 바뀐 상태였음을 발견하고 수정함.

5️⃣ 음성인식 속도 및 정확도 병목 현상 해결함 - "왜 느리지"에서 시작해, 병목이 세 번 옮겨감: 말하고 화면이 바뀌기까지 4~5초가 걸리는 문제에 대해, Claude는 추측으로 파라미터를 만지지 말고 구간별로 시간을 측정해볼 것을 제안함. - 6가지 설정을 바꿔가며 소리를 내고 로그를 남겨 측정해보니, 가벼운 모델은 한국어를 못 알아듣고, 빠르다고 알려진 최신 모델은 오히려 1.7배 느리며, 오디오 길이를 줄여도 속도가 그대로인 등 초기 가설이 모두 틀렸음을 확인함. - 실제 범인은 한 달 전에 띄워놓고 잊어버린 옛날 프로그램이 46시간째 CPU를 389% 점유하고 있었던 것이며, 이로 인해 로나에게 7번의 간식이 자동 배출된 사실도 발견함. - 병목 ①: 소리 감지 — 아무리 만져도 안 되는 벽: 속도를 잡은 후 인식이 들쭉날쭉하는 문제가 발생하여, "소리가 났는지 판단하는 기준값"을 조정하려 시도함. - Claude가 배경 소음 214개를 측정해 보여주며 조용할 때 소음(0.019)이 판정 기준선(0.018)을 이미 넘고 있고, 목소리와 소음 차이가 5배밖에 나지 않아 소리 크기만으로 발화를 가려내는 것은 불가능하다고 분석함. - 이 방향이 답이 없음을 인정하고, "로나 주간 보여줘"와 같이 호출어를 길게 바꿔 테스트하자 7번 중 7번 모두 성공함. - 시스템이 3초 구간의 평균 소리 크기를 보기 때문에 짧은 "주간"은 정적에 희석되지만, 긴 호출어는 평균이 살아남아 인식률이 높아지는 원리를 파악함. - 병목 ②: 받아쓰기 — 이번엔 표기가 틀렸어요: 소리 감지 문제는 해결되었으나, "주간"을 "주관", "월간"을 "웨감" 등으로 잘못 받아쓰는 문제가 발생함. - 자주 틀리는 표기를 사전처럼 등록하기로 했고, Claude는 "주관적으로"와 같은 일상 대화에서 오작동하지 않도록 "주관보여"와 같이 뒤따르는 말까지 묶어서 등록할 것을 제안함. - 일상어와 헛소리 13개로 오작동 검증 후 반영하여, 인식률을 14%에서 75%로 크게 향상시킴. - 인식 문제는 소리 감지, 받아쓰기, 단어 판정의 세 관문으로 이루어져 있으며, 각 단계별로 병목이 다름을 학습함.

6️⃣ 보드 손상 및 교체, 네트워크 문제 해결함 - 급식기와 화면을 합체하려고 전원을 넣었을 때 급식기 쪽 보드가 응답이 없고, ESP32 칩이 과열되는 문제가 발생함. - Claude는 바로 예비 보드를 사용하기보다, 모터 드라이버가 범인일 경우 두 번째 보드도 손실될 수 있음을 경고하며 선택권을 주었음. - 결국 지난 검볼머신에서 보드를 뽑아 이식했고, 발열 정상 및 모터 작동도 원활하게 확인함. - 이 과정에서 폰이 IP 주소 하나를 뺏어가 신호는 받아주지만 실제 통신만 거부되어 기계를 의심하게 되는 네트워크 문제를 발견함.

7️⃣ 느린 화면 전환 개선 및 숨겨진 문제 발견함 - 음성을 글자로 바꾸는 노트북의 처리 시간(3.9초)을 줄일 수 없어, 그 시간 동안 화면이 정지하는 문제를 해결하고자 함. - Claude에게 화면 전환 시 스피너나 다른 표시를 통해 지루함을 덜 수 있는지 검토를 요청함. - 말풍선 안에 점 3개를 차례로 켜지게 하여 "듣고 있어요"를 표시함으로써, 지연 시간 자체는 줄지 않았지만 재발화를 막아 오작동을 줄이는 효과를 얻음. - 점을 붙이니 안 보이던 게 보였어요: 점을 띄운 후, 아무 말도 안 했는데 점이 자꾸 뜨는 이상 현상을 발견함. - 로그를 확인한 결과, 94번 반응 중 실제 글자가 나온 것은 24번뿐이었고, 나머지 70번은 헛것을 들은 것이었음을 파악함. - Claude는 인식 기준값은 건드리지 않고, "점을 띄울지"만 정하는 별도 기준을 새로 두어, 잘못 걸러도 인식에는 영향이 없도록 손해가 비대칭인 영역을 분리하여 처리할 것을 제안함.

8️⃣ 효과음 추가 및 스피커 제약 사항 관리함 - 디스플레이에 스피커가 달려있어 소리도 내고 싶었으며, Claude에게 어떤 소리를 낼 수 있는지 문의함. - Claude가 한국어 안내 음성을 만들어 들려주었으나 어색하여 기각하고, 효과음만 사용하기로 결정함. - Claude가 효과음 후보 16개를 만들어 맥에서 먼저 들려주는 방식으로 빠르게 선택할 수 있도록 지원함. - 화면음(주간·월간 화면 전환 시), 트릿음(간식 배출 시) 두 가지 효과음을 선정함. - Claude는 소리를 내는 동안 마이크가 멈춘다는 제약을 설명하며, "지금 마이크가 일하는 중인가?"를 기준으로 화면별 소리 재생 여부를 정리함. - 스피커는 소리를 낼 때만 켜게 하여, 스피커가 자신의 소리를 마이크로 다시 듣고 말로 착각하는 오작동을 방지함.

9️⃣ 발표 직전 액정 파손 및 비상 대처함 - 발표 전날 밤, 액정이 눌린 것처럼 화면 한가운데가 검게 번지는 물리적 파손이 발생함. - 초기에는 소프트웨어 문제인 줄 알고 재부팅을 시도했으나, Claude는 재부팅해도 같은 자리가 같은 모양으로 번지면 물리적 손상임을 판단함. - 하필 번진 자리가 말풍선 위치여서 "Say Rona treat" 문구가 통째로 보이지 않는 문제가 발생함. - 새 화면 배송에 시간이 오래 걸리고 발표는 다음 날이어서 긴급한 상황이었음. - Claude는 화면이 완전히 죽은 것이 아니라 가운데 띠만 상했으니, 글자를 성한 자리로 옮기자는 현실적인 대안을 제시함. - 말풍선을 아래쪽 성한 구역으로 내리고, 대기 중 점 3개도 말풍선을 따라가도록 조치함. - 코드에 액정 파손 시 임시 배치임을 명시하고, 새 패널 교체 시 한 줄만 되돌리면 원래 배치로 돌아오도록 "손상 모드를 켜고 끄는 스위치 한 줄"로 만들어두었음.

📚 23기 24시간AI서버

✍️ 미니 홈서버를 지향하는 스터디에서 발표 이틀 전에 Docker→Render로 옮긴 이유

강희주

하려던 것 📝

• 발표 안정성을 위해 로컬 Docker 서버를 Render로 이전한 사례

• 지난 발표에서 Zoom, 화면 공유, Chrome, Docker Desktop 동시 실행으로 노트북 메모리 사용률이 98%까지 상승하여 버벅이는 문제가 발생함.

• 노트북 메모리 부하를 줄이기 위해 로컬 Docker에서 실행되던 서버를 클라우드 기반의 Render로 이전하고자 함.

• 청중에게 제공할 링크 화면을 보완하고 완성된 시연을 보여주고자 함.

활용한 툴 ⚒️

• 게시글에 AI 도구나 툴을 활용한 내용은 명시적으로 언급되지 않았습니다.

진행 세부 내용 🔍

• 1️⃣ 지난 발표에서 서버보다 먼저 멈춘 노트북

• 로컬 Windows 노트북의 Docker Desktop에서 Express 서버, 53만 건의 SQLite DB, 지도 화면, 운영자 관제 화면을 Docker 컨테이너로 묶어 실행함.

• Docker가 앱의 실행 환경을 포장할 뿐, 실행하는 컴퓨터의 자원을 늘려주지 않음을 인지함.

• Zoom, 화면 공유, Chrome, Hermes, Docker Desktop이 동시에 올라왔을 때 사용 메모리가 98%까지 올라가 노트북이 버벅이는 문제 발생함.

• Docker를 계속 쓰는 것과 로컬에서 Docker를 실행하는 것을 같은 질문으로 묶으면 안 된다는 것을 깨닫고, Docker 이미지를 Render에서 실행하기로 결정함.

• 로컬 Docker는 개발 및 되돌리기 용도로 남기고, 발표용 서버는 Render의 관리형 Web Service로 옮기기로 함.

• 2️⃣ Render로 옮기자 53만 건의 상권 DB가 유료 디스크가 됐습니다

• 기존 Docker 이미지에 약 221MB의 53만 건 상가 SQLite 파일이 포함되어 있었으며, 로컬에서는 Windows 폴더에 연결하여 컨테이너가 바뀌어도 데이터가 유지됨.

• Render에서 기존 DB의 영속성을 유지하려면 Persistent Disk가 필요하며, 이는 Web Service 비용 외에 추가 비용이 발생함을 파악함.

• 발표 시 청중이 만드는 북마크는 장기 보관할 업무 데이터가 아닌 임시 실습 상태이고, 53만 건 상가 DB는 크고 오래 보존해야 함을 판단함.

• 구조 변경을 통해 53만 건 상가 검색은 공단 Open API를 사용하고, 북마크는 발표 세션 동안만 유지되는 작은 임시 SQLite에 저장하도록 변경함.

• Render에 Persistent Disk를 별도로 붙이지 않아, 배포 또는 서버 재시작 시 검색 스냅샷과 북마크는 초기화되도록 함.

• 배포가 데이터의 상태, 위치, 보존 기간을 다시 묻는 일임을 경험하며 컨테이너, 관리형 서버, Persistent Disk, Open API에 대한 이해를 재정립함.

• 3️⃣ 급하게 갈아엎을수록 되돌아갈 길부터 남겼습니다

• 발표 이틀 전 Open API 권한을 막 받은 상황에서 기존 DB를 지우려 했으나, 리허설까지 통과한 뒤 제거하자는 반려봇의 제안에 따라 기존 상태를 동결함.

• 전체 테스트 130개 통과, 221MB SQLite 파일, 537,489건 상가, 기존 북마크 6건 등 기준선을 설정한 뒤 Open API 전환을 시작함.

• API 방식이 실패할 경우 SQLite 공급자로 돌아갈 수 있도록 두 경로를 한동안 함께 유지함.

• Render 배포 시, 참가자/발표자용 토큰이 서버가 요구하는 형식과 맞지 않아 서버 실행이 중단되는 문제(배포 실패)를 겪었으나, 이는 보안 장치가 의도대로 작동한 결과임을 확인함.

• 토큰을 정상 등록한 뒤에도 인증 검사에서 401 오류가 발생했는데, 이는 검사 프로그램이 `token` 칸이 아닌 `access` 칸에 값을 넣고 있었기 때문임을 발견함.

• 환경변수는 이름만 같다고 같은 설정이 아니며, 값 수정 후 새 배포가 값을 읽었는지, 서버 코드가 정확한 변수 이름을 찾는지, 검사 프로그램이 서버가 약속한 요청 형식을 사용하는지까지 확인해야 함을 학습함.

• 교정 후 Render의 Docker 서버 한 대를 대상으로 외부 HTTPS 접속부터 권한 분리, 인증 쿠키 보안, 공단 상가 검색, 북마크 생성, 관제 화면의 실시간 반영, 검증용 데이터 삭제까지 한 흐름으로 실행하여 238개의 자동 테스트를 완료함.

• 4️⃣ LTE에서 접속은 성공했는데 검색이 안 됐습니다

• 실제 휴대전화·LTE 접속 테스트(Gate 9)에서 참가자 화면이 열리고 지도도 떴으나, 상가 검색 버튼을 누르자 `검색을 완료하지 못했습니다.`라는 오류가 발생함.

• 위치 검색은 200이었지만 공단 상가 검색은 502 오류를 반환했으며, 로컬 Docker에서는 정상 동작하던 공단 API가 Render에서만 실패하는 것을 확인함.

• Render에 등록된 `SBIZ_API_API_KEY`가 로컬의 정상 키와 다름을 발견함.

• 키를 수정하고 다시 배포하자 코엑스 100m 검색이 200으로 돌아왔고 252개 상가가 조회되었으며, 북마크도 휴대전화에서 저장됨.

• 자동 테스트는 코드 계약과 많은 실패 경로를 빠르게 확인하지만, '사이트가 열린다 ≠ 지도가 뜬다 ≠ 외부 API 검색이 된다 ≠ 북마크가 된다 ≠ 실제 휴대전화에서 쓰기 편하다'는 서로 다른 증거임을 깨달음.

📚 23기 데이터대시보드

✍️ # [Claude Code + AI 에이전트] AI와 함께 만든 미국 주식 포트폴리오 대시보드: 테스트를 통과해도 실전에서 틀릴 수 있었다

곽재현

하려던 것 📝

• 미국 주식·ETF 한 계좌 거래를 정확하게 기록하는 로컬 대시보드 구축 사례

• 매수와 매도가 반복돼도 평균단가와 손익이 한 푼도 틀리지 않는 거래원장을 만드는 것을 목표로 함

• 증권사 화면만으로는 원하는 기준의 거래원장, 이동평균단가, 수수료 반영 실현손익을 한곳에서 보기 어려운 문제를 해결하고자 함

• 차트보다는 가장 먼저 틀리면 안 되는 '숫자 정확성'을 확보하는 것에 집중하여 범위를 줄여 개발함

활용한 툴 ⚒️

• Claude Code: 테스트 작성 및 코드 구현

• AI 에이전트 빅맥: 프로젝트 매니징(PM) 및 품질 보증(QA)

• 독립 리뷰어: 구현된 코드에 대한 읽기 전용 검수

진행 세부 내용 🔍

• 1️⃣ 역할 분담 및 권한 설정

• AI 사이에도 권한을 나누어 저스틴(본인)은 목표, 범위, 중요한 제품 결정 및 외부 호출 승인을 담당함

• 빅맥(AI)은 PM·QA 역할을 맡아 완료 조건 설정, 숫자 검증, 통합 보고를 수행함

• Claude Code(AI)는 테스트를 먼저 작성하고 코드를 구현하는 방식으로 진행함

• 독립 리뷰어(AI)는 구현한 측과 분리하여 반대 관점에서만 코드를 검수함

• 특히, 실제 외부 서비스 호출은 본인의 승인 없이는 진행하지 못하도록 막아두어 한도 소모를 방지함

• 2️⃣ 거래원장 핵심 로직 구축

• 차트 구현보다 평균단가, 수수료 반영 실현손익 등 거래원장의 숫자 정확성에 집중하여 구현함

• 저장 결과가 불확실할 때 프로그램이 자동으로 재시도하지 않고 멈추고 사람에게 알리도록 설계함

• 보유 수량보다 많이 파는 입력은 저장 전에 차단하여 잘못된 거래를 방지함

• 화면 개발에 앞서 숫자의 정확성을 먼저 확보하는 데 주력함

• 3️⃣ 무료 API 호출 한도 관리

• 하루 250회로 제한된 무료 API 한도를 넘기지 않기 위한 전략을 수립함

• 호출하기 전에 오늘 사용 횟수를 기록하고, 실패한 호출도 한 번 쓴 것으로 간주하여 한도에 포함시킴

• 기본 실행은 실제 호출이나 저장이 없는 미리보기(dry-run) 모드로 설정함

• 실제 호출은 `--execute` 명령어를 직접 붙여야만 가능하도록 하여 실수로 인한 한도 소모를 막음

• API 키는 'configured'라고만 표시되고 값은 절대 출력되지 않도록 보안을 강화함

• 4️⃣ 사건 1: 테스트와 실제 API 응답 불일치

• 실제 API를 단 2번만 호출했으나 `adjClose` 필드 누락으로 둘 다 실패함

• 테스트에 사용된 가짜 응답에는 해당 필드가 있었으나 실제 응답에는 없어 프로그램이 이를 필수 필드로 요구하며 거부함

• 응답 원문과 API 키를 출력하지 않고 필드 이름만 확인하여 문제를 진단함

• 해결책으로 `adjClose` 필드가 있으면 원래대로 사용하고, 없으면 이미 검증된 종가를 대신 사용하며, 값이 이상할 경우 조용히 대체하지 않고 거부하도록 수정함

• 이 경험을 통해 '테스트 통과'가 '실제로 쓸 수 있다'는 의미와 다르다는 것을 깨달음

• 수정 후 AAPL 1,254행, SPY 1,254행, 총 2,508행의 5년치 데이터가 중복, 빈 값, 음수, 앞뒤 안 맞는 가격 없이 저장됨

• 5️⃣ 사건 2: 장중 데이터 문제로 인한 거래량 오류

• 저장된 데이터를 확인하던 중 특정 날짜의 거래량이 전날의 6분의 1도 안 되는 비정상적인 수치임을 발견함

• 이는 미국장이 열린 지 얼마 안 된 시각에 수집된, 아직 확정되지 않은 장중 값이었음

• '이미 저장한 데이터는 덮어쓰지 않는다'는 안전 규칙이 오히려 장중 값을 확정값으로 변경하지 못하게 막는 문제에 직면함

• 해결책으로 미국 동부시간 16시 30분(장 마감 및 반영 여유) 전에는 그날 데이터를 아예 받지 않도록 경계를 추가함

• 날짜를 직접 지정해도 경계에 걸리면 조용히 잘라내지 않고 거부하도록 시스템을 보완함

• 이 수정은 구현과 1,133개의 테스트를 통과했으며 현재 검수를 기다리는 중임. 이미 저장된 장중 데이터 2행은 백업 후 정리할 예정임