9.9 KiB
7교시 바이브 코딩 · 요청서 tops (가장 먼저 읽기)
- 순서: 이 요청서 → 내 정리
~/vibe/tops/Doc/TODO.md(8분) → VIBE-Q-TOPS.md의 순서대로Doc/SPEC.md→Doc/IMP-PLAN.md→ 단계별로 만들기 → 설치 · 다른 곳에서 쓰기 → 수업이 끝나면VIBE-A-TOPS.md(정답본)로 확인 - 이 문서는 만들어 달라는 사람의 말입니다. 요구 사항 표도, 단계도 없습니다. 그것을 뽑아 내는 것이 첫 일입니다. 72일차
tbench부터 78일차tcheck까지와 같은 순서입니다.
flowchart LR
REQ["요청서<br/>(사람의 말)"] --> TODO["Doc/TODO.md<br/>만들고 싶은 것 ·<br/>요청의 말 정리"] --> SPEC["Doc/SPEC.md<br/>확인할 수 있는 요구"] --> PLAN["Doc/IMP-PLAN.md<br/>엔진 → TUI 단계"] --> RUN["단계별로 만들기 ·<br/>직접 확인"] --> USE["uv tool install<br/>다른 곳에서 쓰기"]
생활 속 예 · 회진 도는 의사의 손바닥 현황판. 오늘 병원(n8n)에 아침 인수인계 시스템을 만들었습니다: 환자 상태표(사실), 물어보면 답하는 간호사실(질문 답변), 아침 브리핑(먼저 볼 것). 그런데 회진을 도는 의사는 간호사실까지 오지 않고 손바닥 화면으로 보고 싶어 합니다. 화면이 따로 판정을 내리면 안 됩니다 — 간호사실이 "빨강"이라고 한 환자는 손바닥에서도 빨강이어야 합니다. 그리고 손바닥 화면으로는 보기만 하고, 처방은 하지 않습니다.
tops는 오늘의 운영 도우미를 터미널에서 보는 손바닥 현황판입니다.
왜 요청서부터인가
요구 사항 표를 통째로 에이전트에게 주고 "이대로 만들어 줘"라고 하면, 무엇이 만들어지든 내가 판단할 기준이 없습니다. 실무에서는 요구 사항 표가 오지 않고, 이 요청서 같은 사람의 말이 옵니다. 오늘 Lab 01 예제 1에서 morning과 기준 대시보드를 먼저 눈으로 비교해 본 것과 같습니다: 무엇이 보여야 하는지 정해야 맞게 보였는지 말할 수 있습니다.
| 단계 | 누가 | 결과 |
|---|---|---|
| 요청 → 할 일 목록 | 나 | Doc/TODO.md: 요청의 말 ①~⑫를 내 말로, 만들고 싶은 것 |
| 할 일 → 요구 | 나 (에이전트와 다듬어도 됨) | Doc/SPEC.md: 요구마다 "됐다 / 안 됐다"를 말할 수 있는 확인 방법 |
| 요구 → 단계 | 나 (에이전트와 다듬어도 됨) | Doc/IMP-PLAN.md: 엔진 단계와 화면(TUI) 단계로 나눈 순서 |
| 단계 → 코드 | 에이전트 | 처음 요청 한 번 + 단계마다 한 줄, Doc/*.md를 읽게 함 |
| 확인 | 나 | 직접 uv run tops …, pytest, n8n 브리핑 · my-ops-facts와 색 · 숫자 비교, 요구 표에 체크 |
요청 (운영 당번 · 팀장에게서 온 메시지, 그대로)
오늘 n8n으로 운영 사실 · 질문 답변 · 브리핑 · 평가까지 만들었다고 들었어요. 그런데 당번은 아침마다 터미널부터 열어요. 브라우저에서 n8n을 열고 웹훅을 부르는 건 번거로워요. 어느 폴더에서나
tops라고 치면 오늘 아침 상태가 보이는 도구가 있으면 좋겠어요.① 영역 여섯(실행 · 알림 · DLQ · 품질 · 비용 · 릴리스)의 색과 숫자를 한눈에요. 오늘 만든 사실(
my-ops-facts) 그대로요.② 제일 중요한 거요. 색을 도구가 따로 정하면 안 돼요. n8n 브리핑이 빨강이라는데 터미널이 노랑이면 아무것도 못 믿어요. 숫자도 다시 세지 말고요 (77 · 78일차에 두 벌 정의로 고생했잖아요).
③ 지난주 말고 다른 기간도 볼 수 있게요. 첫 주를 다시 보고 싶을 때가 있어요.
④ 터미널에서 질문도 하고 싶어요. 오늘 만든 도우미(
my-ops-ask)에 그대로 보내서, 무엇으로 답했는지(영역) · 숫자 확인이 됐는지 · 거절했는지 같이 보여 주세요.⑤ 절대로요. 이 도구로 재처리 · 삭제 · 카나리 끄기 같은 걸 하면 안 돼요. 읽기만요. 실수로라도 바뀌면 큰일이에요.
⑥ 아침 회의에 붙일 브리핑(
my-ops-brief)도 그대로 터미널에서요.⑦ 출처가 하나 멈춘 날 있잖아요. 그날은 모른다고 보여 주세요. 0이나 초록으로 보이면 안 돼요.
⑧ 지난번에 만든 도구들 있죠 —
tlog·tcheck. 다시 만들지 말고 있는 걸 불러서 같이 보여 주면 좋겠어요. 없는 사람은 없다고만요.⑨ 도우미를 고칠 때마다 골든 질문 평가(
my-ops-eval)를 터미널에서 돌리고 싶어요. 기준보다 낮으면 스크립트가 알 수 있게 종료 코드로요.⑩ 사람들이 도우미에게 무엇을 물었는지(감사 기록)도 볼 수 있게요.
⑪ 화면에서 보고 싶어요. 영역 · 브리핑 · 질문하기 · 감사 기록을 탭으로 나누고, 새로고침 키도요.
⑫ 스크립트에서 쓸 거라 종료 코드가 중요해요. 됐다 · n8n을 못 읽었다 · 쓰는 법이 틀렸다 · 빨강이거나 평가가 떨어졌다를 서로 다른 번호로요. 다른 프로그램이 읽을 수 있게 JSON으로도요.
아, 시험할 때 진짜 n8n이 없어도 돌아가야 해요. n8n이 꺼진 날에도 도구가 죽지 말고 "못 읽었다"고 해 주세요.
함께 받은 것
| 파일 · 자료 | 메모 |
|---|---|
오늘 n8n 웹훅 http://localhost:5678/webhook/… |
my-ops-facts ({"from", "to"}) · my-ops-ask ({"question"}) · my-ops-brief · my-ops-eval ({"cases", "min_score"}) |
오늘 데이터 API http://localhost:8800 |
POST /audit/list (감사 기록). 상태를 바꾸는 주소는 쓰지 않음 (/dlq/update · /ops-reset · /budget · /admin/fault) |
~/aio-01d4-stu/Last3Mon/79/requests/ |
week1.json · week2.json · ops-golden.json(골든 질문 8) |
| 내 n8n의 응답 | uv run tools/flow.py call my-ops-facts requests/week2.json 등으로 받은 사실 · 답 · 브리핑 · 평가 응답 → 파일로 저장해 테스트용 사본 (수업 뒤에는 정답 실행 기록 answers/에도) |
| AGENTS.md 3절 | 사실의 칸 · 영역별 상태 기준 · 브리핑 표의 숫자 꼴 · 거절 이유 (오늘의 규칙서) |
72~78일차 ~/vibe/* |
tlog (slo --json) · tcheck (있으면) |
| Python 표준 라이브러리 | json, urllib.request, subprocess. TUI는 Textual |
할 일 · 요청을 내 할 일 목록으로 (8분, 에이전트 없이)
~/vibe/tops/Doc/TODO.md를 만들고 요청의 말 ①~⑫와 맨 끝 부탁을 내 말로 한 줄씩 옮깁니다. 아직 "어떻게"는 쓰지 않습니다. 무엇을 · 왜만 씁니다. 에이전트에게 맡기지 않고 직접 씁니다.
# tops TODO
## 만들고 싶은 것 (한 문단)
어느 폴더에서나 `tops`로 오늘 n8n 운영 도우미(my-ops-*)의 사실 · 답 · 브리핑 · 평가를 터미널에서 보는, 읽기만 하는 ...
## 요청의 말 → 할 일
| # | 요청의 말 (짧게) | 할 일 (내 말) | 꼭 · 나중 |
| --- | --- | --- | --- |
| ① | 영역 여섯 · 색 · 숫자 | | 꼭 |
| ② | 색을 따로 정하지 않음 | | |
| ... | | | |
| 끝 | n8n 없이 시험 · 꺼져도 안 죽음 | | |
## 요청에 없지만 걱정되는 것
## 오늘 50분 안에 못 할 것 같은 것
예 하나만 보여 드립니다.
| 요청의 말 | TODO에 쓸 할 일 (내 말) | 다음 단계(SPEC)에서 바뀔 모양 |
|---|---|---|
| ② "색을 도구가 따로 정하면 안 돼요" | "my-ops-facts의 health · overall을 그대로 쓰고, 숫자는 브리핑 표의 꼴(×100 · 두 자리)로 보이기만. 기준(0.01 · 0.8 …)을 코드에 쓰지 않음" |
R1: 사실 파일의 health.cost를 green으로 바꿔 주면 비용이 92%여도 🟢로 보임 (tops가 다시 판정하지 않는다는 증거) |
▶ 1단계 · 꼭 할 것과 나중에 할 것
요청의 말이 열두 개입니다. 50분 안에 다 만들기 어렵습니다. 당번이 가장 아파하는 것은 "n8n과 같은 색"(믿을 수 있나)과 "읽기만"(실수로 바꾸지 않나)입니다. 그리고 질문 · 브리핑 · 평가 · 화면을 만들려면 먼저 무엇이 있어야 하나요? (n8n을 읽는 층 → 사실을 보여 주기 → 질문 · 브리핑 → 평가 · 감사 → 화면)
▶ 2단계 · 걱정되는 것 (숨은 요구의 씨앗)
- ② "다시 세지 말고": 오류율 · 비율을 tops가 계산하면 77일차처럼 정의가 두 벌이 됩니다. 사실의 값을 꼴만 바꿔 보입니다 (0.0588 → 5.88%).
- ⑤ "읽기만": "조심해서 안 부른다"가 아니라 부를 수 있는 주소를 정해 두고 그 밖은 막습니다. 테스트로 확인할 수 있게.
- ⑦ "모른다고":
cost가null이면 숫자 칸에 0이 아니라 "응답 없음", 색은unknown(오늘 Lab 01 과제 2). - ⑧ "다시 만들지 말고": 지난 도구는 명령으로 부르고(
tlog slo --json), 없으면 "설치되지 않음". 지난 도구의 코드를 복사해 오지 않습니다. - ⑨ · ⑫ "종료 코드": 평가가 떨어진 것(4)과 n8n을 못 읽은 것(1)이 다른 번호여야 스크립트가 "도우미를 고쳐라"와 "n8n을 켜라"를 구분합니다.
- ⑪ "탭": 탭 하나가 못 읽어도(브리핑 웹훅이 없음) 다른 탭은 보여야 합니다.
- 끝 "n8n 없이 시험": n8n · 데이터 API를 대신할 작은 가짜 서버, 그리고 내 n8n이 낸 응답을 저장한 사본.
그다음
VIBE-Q-TOPS.md를 엽니다. 거기서 Doc/TODO.md → Doc/SPEC.md → Doc/IMP-PLAN.md → 단계별 구현 → 확인 → uv tool install → 다른 곳에서 사용 순서로 갑니다. VIBE-Q의 요구 표는 내 SPEC을 쓴 뒤에 비교하는 데 씁니다.