📌 한 줄 요약
매달 9개 조 TBM 일지를 출력·펀치·배포하고, 한 달 뒤 수거해서 빈 서명 칸을 찾아다니던 일을 '조별 QR + 휴대폰 손서명 웹앱'으로 바꿨습니다. Claude Code에 gatekit 플러그인을 얹어 기획 → 화면 → 작업 분해 → 완료 기준 → 빌드 → 독립 검증까지 갔고, 저는 코드를 한 줄도 쓰지 않았습니다. 질문 대부분은 번호 하나로 답했습니다.
━━━━━━━━━━━━━━━━━━━━
■ QR 손서명 웹앱 도입 배경
▶ 시작하게 된 계기
Claude Code 스터디에서 gatekit 플러그인을 쓰고 있습니다. 1주차에는 "소모품 구매 도우미"를 프로토타입까지만 기획했는데, 이번에는 제 실제 업무 하나를 정해서 끝까지 돌아가는 앱을 만들어 보기로 했습니다.
(✏️ 주제를 TBM으로 바꾼 이유를 한두 줄 적어 주세요. 예: "매달 반복되는 일이라 효과가 바로 보일 것 같아서")
▶ 문제: 서명 누락은 한 달 뒤에야 보인다
저는 안전 서류를 맡고 있습니다. TBM(작업 전 안전점 검 회의) 일지는 이렇게 돌아갔습니다.
1. 매달 9개 조 한 달치 일지를 제가 출력하고 펀치해서 현장에 나눠 줍니다. 일지에는 조별 체크리스트, 회의록 칸, 미리 인쇄한 조원 명단, "이 내용을 잘 들었다"는 서명 칸이 있습니다.
2. 조장님이 매일 아침 조원을 모아 체크리스트를 체크하고 서명을 받습니다.
3. 다음 달 일지를 배포할 때 지난달 일지를 수거해서 날짜별로 넘기며 빈 서명 칸을 눈으로 찾습니다.
4. "휴가/결근"도 안 적힌 빈 칸이 있으면 그 부서를 직접 찾아가 서명을 다시 받습니다.
5. 정리한 일지는 바인더에 철해 두고, 점검·감사 때 꺼냅니다.
제일 큰 문제는 누락이 한 달 뒤 수거할 때에야 드러난다는 점이었습니다. 9개 조, 50~60명 규모입니다.
▶ 목표
· 매달 하던 출력·펀치·배포·수거를 0회로. 조별 QR은 처음에 한 번만 붙입니다.
· 서명 누락을 TBM 당일에 관리 화면에서 확인합니다.
· 그리고 제가 제일 신경 쓴 것: 조장님들 일이 늘지 않을 것.
━━━━━━━━━━━━━━━━━━━━
■ QR 손서명 웹앱 개발 과정
▶ 사용한 도구
· Claude Code (데스크톱 앱): 대화로 기획하고, 코드 작성·테스트·수정까지 맡김
· gatekit 플러그인: 기획 → 화면 → 작업 → 완료 기준 → 빌드 → 검증을 단계별 명령으로 진행. 완료 기준을 승인하기 전에는 AI가 코드를 못 쓰게 막아 줌
· 결과물: Next.js 웹앱. 휴대폰 브라우저로 여는 웹페이지라 앱 설치·로그인 없음
▶ 전체 흐름
1단계 /gatekit:interview
질문 하나씩 답하며 기능을 정함 → 비슷한 서비스 리서치 → 기획서
→ 기능 13개, 가정 24개
2단계 /gatekit:mockup
화면 명세와 클 릭해 볼 수 있는 프로토타입
→ 휴대폰 6화면 + PC 관리 6화면
3단계 /gatekit:tasks
만들 일을 작업 단위로 쪼갬
→ 작업 9개
4단계 /gatekit:gate
"다 됐다"의 기준을 미리 정하고 승인
→ 완료 기준 8개
5단계 /gatekit:build
AI가 작업을 하나씩 만들고, 작업마다 테스트가 통과해야 넘어감
→ 작업 9개 모두 통과
6단계 /gatekit:verify
만든 세션이 아닌 별도 평가자가 직접 눌러 보며 검증
→ 아래 결과 참고
10월 12일 오전에 인터뷰를 시작해서 13일 밤에 최종 검증까지 마쳤습니다. 퇴근하고 집에 와서 이어서 한 시간도 포함입니다.
━━━━━━━━━━━━━━━━━━━━
▶ 기획 인터뷰 (/gatekit:interview)
처음 입력은 이 한 줄이었습니다.
💬 /gatekit:interview TBM 교육 및 서명관리하는 어플을 제작하고싶어 어플이든 QR통한 서명관리든
그다음부터 AI가 한 번에 하나씩 묻고, 질문마다 추천안과 번호 선택지를 줬습니다. 지금 어떻게 하고 있는지를 물었을 때는 제 말로 답했습니다.
💬 순서는 맞고 번거로운단계는
1. 한달치를 내가 다 출력 및 펀치해서 현장에 배포
2. 배포시 지난단 완료된 TBM일지를 다시 수거하여 별도정리
이과정중 서명 누락 등이 발생하면 별도로 해당부서 찾아가서 다시 받거나 하는 일이있음
나머지 질문은 대부분 "1"만 입력했습니다.
🤔 "조장님 일이 늘면 안 되는데…"
중간에 제일 걱정되던 걸 그대로 물어봤습니다.
💬 고민인게 조장님들한테 너무 일이 안됬으면 좋겠거든 ? 근대 어플로 체크하는거면 시간소요가 꽤되지않을까 ?
AI가 준 선택지 중 1번을 골랐고, 이게 앱의 핵심 설계가 됐습니다.
· 체크리스트는 전부 체크된 상태로 시작합니다. 문제 있는 항목만 눌러서 해제하고, 이상 없는 날은 "저장" 한 번이면 끝납니다.
· 회의록은 비워도 되고, "특이사항 없음" 같은 문구 버튼을 눌러 넣을 수 있습니다.
· 안 온 사람은 같은 화면 명단에서 "휴가"/"결근"만 누르면 됩니다. 마감 버튼은 따로 없고, 그날이 끝날 때까지 서명도 사유도 없으면 제 관리 화면에 "누락"으로 뜹니다.
이어서 정한 것들 (질문 → 고른 답)
· 본인 확인 → 종이와 같은 수준. 처음 한 번 명단에서 이름을 고르면 휴대폰이 기억합니다. 조장님만 4자리 PIN을 한 번 넣습니다. (문자 인증은 비용과 개발 부담이 커서 뺐습니다)
· 증빙 형태 → 지금 종이 일지와 같은 배치의 월별 PDF
· "교육" 부분 → 제가 제안했습니다. 주의사항을 카드뉴스 이미지 2장으로 만들어 서명 직전에 보여 주고, 끝까지 넘겨야 서명 칸이 열립니다.
· 잘못된 서명 → 당일은 조장님이 취소, 다음 날부터는 저만 취소. 취소해도 기록은 지우지 않고 누가·언제·왜를 남깁니다.
· 명단·체크리스트 관리 → 처음 한 번 등록하고 바뀔 때만 고칩니다. 퇴사자는 지우지 않고 "비활성"으로 돌립니다.
· 현장 통신 → 9개 조 TBM 장소 모두 휴대폰 데이터가 잘 터진다고 확인해서, 오프라인 서명 기능은 뺐습니다. AI가 "이게 틀리면 QR 방식 전체가 흔들린다"며 문서 쓰기 전에 한 번 더 확인한 질문입니다.
💡 리서치로 추가된 기능
인터뷰 끝에 AI가 비슷한 TBM·안전관리 서비스와 관련 자료를 웹에서 조사해서, 대화에서 안 나온 기능을 A~G로 제안했습니다. 저는 이렇게 답했습니 다.
💬 a, b, d 는 추가해줘 c는 추가하고 싶은대 우선 기능만 먼저 구현하고 나중에 추가할께
· A. 서명 시각과 변경 이력: 서명은 휴대폰 시계가 아니라 서버 시각으로 저장되고, 한 번 저장되면 고칠 수 없고 취소만 됩니다. 나중에 몰아서 서명한 게 아님을 보여 주는 장치입니다.
· B. 체크 해제 항목에 조치 한 줄: 조장님이 항목을 해제하면 "어떻게 조치했는지" 칸이 뜹니다. 이상 없는 날에는 안 나옵니다.
· D. 조원이 위험요소를 남기는 칸: 서명 화면 아래에 한 줄 글과 사진 1장. 비워도 서명됩니다.
· C. 외국인 근로자용 다국어 표시는 다음 단계로 미뤘습니다.
최종 기능은 13개(F1~F13), 확인되지 않은 판단은 ⚠️ 가정 24개로 표에 남았습니다.
━━━━━━━━━━━━━━━━━━━━
▶ 화면 설계 (/gatekit:mockup)
참고할 디자인이 없어서 새로 제안받았고, 클릭해 볼 수 있는 HTML 프로토타입이 나왔습니다. 확정 전에 하나 물어봤습니다.
💬 확정전에 질문이있어 체크리스트 항목은 나중에 수정이 가능하지 ??
관리 화면에서 언제든 고칠 수 있고, 바꿔도 이미 저장된 날의 기록과 PDF는 그날 문구 그대로 남는다는 답을 듣고 확정했습니다. 점검 때 지난 일지 내용이 바뀌면 안 되니까요.
━━━━━━━━━━━━━━━━━━━━
▶ 작업 나누기와 완료 기준 (/gatekit:tasks, /gatekit:gate)
여기가 gatekit에서 제일 인상적이었던 부분입니다.
· 만들 일을 작업 9개로 쪼개고, 작업마다 "이 테스트가 통과해야 끝"이라는 검사를 붙였습니다.
· 전체 완료 기준 8개를 미리 정했습니다: 빈 코드(TODO) 검사, 색상 규칙 검사, 타입 검사, 단위 테스트, 전체 흐름 E2E, 화면 캡처, 휴대폰·PC E2E.
· 제가 승인하기 전까지 AI는 코드를 쓸 수 없습니다. 승인하면 내용이 해시로 고정돼서, 나중에 AI가 기준을 몰래 느슨하게 바꿀 수 없습니다.
━━━━━━━━━━━━━━━━━━━━
▶ 빌드 (/gatekit:build)
"응 다음 진행해줘"라고 하자 AI가 작업 9개를 순서대로 만들었습니다. 작업마다 테스트를 통과해야 다음으로 넘어가고, 9개 모두 통과했습니다.
완성된 화면입니다. (화면 속 이름과 데이터는 테스트용 가상 데이터입니다)
① 조원 — QR을 찍고 서명
오늘 TBM 내용이 위에 보이고, 손가락으로 서명합니다. 획이 없으면 "서명 제출"이 안 눌립니다.
[📷 이미지 첨부: 03-sign.png]
② 조장 — 체크리스트와 출석
전부 체크된 상태로 시작하고, 해제한 항목에만 조치 칸이 뜹니다. 아래 명단에서 휴가·결근을 누르면 끝입니다.
[📷 이미지 첨부: 05-leader.png]
③ 관리자 — 오늘 현황
조별 실시 여부, 서명 수, 미서명자 이름이 당일에 보입니다. 조 카드를 누르면 체크리스트 결과와 서명이 오른쪽에 열립니다.
[📷 이미지 첨부: 06-admin.png]
④ 관리자 — 기록·PDF
날짜별 실시·누락이 보이고, 종이 일지와 같은 배치로 월별 PDF를 내려받습니다. 아래에는 변경 이력이 남습니다.
[📷 이미지 첨부: 07-records.png]
━━━━━━━━━━━━━━━━━━━━
▶ 독립 검증 (/gatekit:verify)
gatekit은 만든 세션이 스스로 채점하지 못하게 합니다. 읽기만 할 수 있는 별도 평가자가 앱을 직접 띄우고 눌러 봅니다.
최종 결과 (10월 13일 밤)
· 완료 기준 8개 모두 ok, 단위 테스트 43개 통과
· QR 진입 → 카드뉴스 → 서명 → 조장 PIN → 체크리스트·휴가 → 관리자 현황 → PDF, E2E 7단계 모두 ok
· 평가자가 따로 확인한 것: 서명 시각을 2000년으로 조작해서 보내도 서버 시각으로 저장됨, 서명 수정·삭제 경로 없음, 다른 조 QR로는 다른 조 서명을 건드릴 수 없음, 관리자 로그인 없이 관리 화면 접근 불가
· 화면 판정 9개 중 8개 ok, 1개 warn (기록 화면 캡처가 데이터 없는 빈 상태로만 찍힘)
━━━━━━━━━━━━━━━━━━━━
■ QR 손서명 웹앱 결과와 배운 점
▶ 결과
· 이틀 동안 기획서(기능 13개) → 화면 12개 → 작업 9개 → 완료 기준 8개 → 실제 동작하는 웹앱까지 나왔습니다.
· 매달 출력·펀치·배포·수거가 필요 없는 구조가 됐고, 누락은 당일 관리 화면에서 보입니다.
· 실제 효과(시간이 얼마나 줄었는지)는 아직 재지 않았습니다. 기획 단계에서도 지금 걸리는 시간을 재지 않았다고 가정 표에 남겨 뒀습니다.
▶ 시행착오 (검증 단계가 잡아낸 것들)
빌드가 "통과"한 뒤에도 독립 검증에서 여러 번 걸렸습니다. 테스트는 통과했는데 사람 눈으로 보면 이상한 것들이었습니다.
· 글꼴이 실제로 안 불러와지고 있었습니다. 설계에는 Pretendard 글꼴이라고 써 놓고 실제로는 로드하지 않았습니다. 평가자 캡처를 보고 알았습니다.
· 이모지 아이콘(📄·📷·🖨)과 화면 아래 빈 띠가 지적돼서 아이콘을 바꾸고 화면이 창 높이를 채우도록 고쳤습니다.
· 오늘 아직 서명 안 한 사람을 "누락"으로 세는 버그와, 변경 이력에 "휴가" 대신 vacation이 그대로 찍히는 문제도 검증에서 나왔습니다.
· 단위 테스트가 너무 느렸습니다(약 115~118초, 제한 120초 경계). 원인은 PDF에 한글 글꼴을 넣는 과정이었고, 글꼴을 미리 변환해 두도록 바꿔서 PDF 테스트가 51초 → 2초가 됐습니다.
· Codex를 평가자로 써 봤다가 돌아왔습니다. 다른 회사 AI로 교차 검증하면 좋겠다 싶어 켰는데, Windows에서 샌드박스 오류가 났고, 한 번 실행에 토큰 약 49만 개를 쓰고 ChatGPT 사용 한도에 걸려 판정도 못 받았습니다. 결국 Claude 평가자로 바꿨습니다.
→ "테스트 통과"와 "쓸 만하다"는 다르다는 걸 배웠습니다. 별도 평가자가 화면을 찍어 보고 판단하는 단계가 있어서 잡을 수 있었습니다.
▶ 배운 점과 꿀팁
1. 걱정을 그대로 물어보세요. "조장님 일이 늘면 안 되는데"라고 했더니 "전부 체크된 상태로 시작" 같은, 혼자서는 못 떠올렸을 설계가 나왔습니다.
2. 리서치 제안은 꼭 받아 보세요. 서버 시각과 변경 이력(A)은 점검·감사 때 진짜 중요한데 저는 생각 못 했습니다.
3. 완료 기준을 먼저 승인하는 방식이 비개발자에게 특히 좋습니다. 코드를 못 읽어도 "이 기준을 통과했다/못 했다"로 판단할 수 있습니다.
4. "통과"를 믿지 말고 검증까지 돌리세요. 위 시행착오는 전부 빌드가 통과한 뒤에 나왔습니다.
5. 다른 AI 평가자는 비용을 먼저 확인하세요. 환경 문제가 있으면 판정 없이 토큰만 많이 쓸 수 있습니다.
▶ 솔직하게: 아직 안 된 것
· 실제 서버 배포(Supabase·Vercel)는 아직 안 했습니다. 지금까지의 검증은 모두 제 PC의 테스트 환경 기준이고, 운영 환경은 "미확인"으로 남아 있습니다.
· 개천절·한글날 같은 휴무일을 입력해야 그날이 "미실시"로 잡히지 않습니다.
· 개인정보 안내는 한 줄 고지로만 했는데, 회사 규정상 동의서가 필요한지는 확인이 필요합니다.
· TBM 기록의 법정 보관 기간은 확인하지 못해서, 일단 삭제 없이 계속 보관하게 했습니다.
▶ 도움이 필요한 부분
· 현장 안전 서류를 웹으로 바꿔 보신 분, 점검·감사 때 전자 서명 기록을 인정받는 데 문제가 없었는지 경험을 듣고 싶습니다.
· TBM 기록 보관 기간을 아시는 분 계시면 알려 주세요.
▶ 앞으로의 계획
1. Supabase·Vercel로 실제 배포
2. 한 조에서 먼저 시범 운영 → 문제없으면 9개 조 전체로
3. 시범 기간에 조장님 몫이 실제로 몇 초 걸리는지, 월 배포·수거 시간이 얼마나 줄었는지 재서 후기 올리겠습니다.
4. 외국인 근로자용 다국어 표시(C) 추가
