kimjisub/agent-skills

증거 보고서

로드 시점 - 결과를 남에게 보여 줘야 하는데 글로는 안 와닿을 때, 그리고 그 증거가 실제 화면일 때. 화면에 드러나는 큰 기능을 구현하거나 고쳤다면 요청이 없어도 완료 보고를 여기서 시작한다. 화면이 없는 문서와 화면 사이 이동 흐름 지도는 대상이 아니다.

목적

실제로 띄워 찍은 화면으로 하나의 질문에 답하는 문서를 만든다. 받는 사람은 코드도 커밋 로그도 읽지 않는다. 그들이 아는 것은 화면뿐이므로, 문서의 무게는 전적으로 그 화면이 실제 구동 결과라는 데서 나온다. 같은 발견을 글머리표 열 줄로 말하는 것보다, 같은 레코드를 두 화면에서 찍어 나란히 둔 사진 두 장이 빨리 이해되고 반박되지 않는다. 큰 기능을 끝내고 이 보고서 없이 "완료했습니다"로 넘기면, 받는 사람이 직접 화면을 열어 확인하는 비용이 그쪽으로 넘어간다.

결과물은 HTML 한 장이다. 받는 사람은 그것을 휴대폰으로 열기도 하고 브라우저 인쇄로 PDF 를 만들기도 하므로, 템플릿이 좁은 화면과 A4 인쇄를 둘 다 맞춰 둔다. PDF 나 Markdown 을 따로 만들지 않는다.

이 스킬에는 고정된 목차가 없다. 먼저 이 문서가 답하는 질문 한 문장을 정하고, 그 질문에서 비교축과 절 구성이 따라 나온다.

질문	비교축	문서가 하는 일
무엇이 바뀌었나	이전 코드 <-> 지금 코드	두 화면을 나란히 놓아 개선을 증명한다
기획대로 되었나, 남은 건 뭔가	기획서, 명세 <-> 지금 화면	조항마다 판정을 붙이고 어긋난 것만 남긴다
우리 원칙대로 되어 있나	원칙, 체크리스트 <-> 지금 제품	제품 전체를 훑은 발견을 원인별로 묶고, 화면으로 보일 수 있는 것을 찍어 증명한다
조건이 바뀌면 뭐가 달라지나	상태 A <-> 상태 B	플래그, 날짜, 권한을 실제로 바꿔 가며 찍는다
지금 어떤 상태인가	축 없음	현재 화면만으로 전체를 훑는다
무엇을 정해야 하나	선택지 <-> 선택지	항목마다 지금 화면, 선택지, 필요한 입력을 짝지어 둔다

축이 둘 이상 섞이는 것이 보통이다. 명세 대조를 하다 보면 "기획에 없는데 이미 있는 것"이 나오고, 그것은 축이 다른 항목이라 절을 따로 세워야 한다. 질문이 흐릿하면 문서도 흐릿해진다. 한 문장으로 안 써지면 문서를 둘로 나눈다.

핵심 원칙

1. 화면은 재현이 아니라 실제 구동 결과다. 기억으로 "이랬을 것"을 만들면 거의 틀린다. 이전 화면에는 지금은 지워진 요소가 있었거나, 기억하는 것보다 문제가 덜하거나 더했다. "이 조건이면 이렇게 보일 것"도 틀린다. 플래그를 실제로 켜 보면 예상과 다른 화면이 나온다. 그래서 보여 줄 상태를 실제로 만든 뒤 찍는다. 그래야 문서에 "재현이 아니라 실제로 동작한 결과입니다"라고 쓸 수 있고, 그 한 문장이 문서 전체의 신뢰를 결정한다. -> Step 3
2. 사진 옆에 값을 둔다. 사진은 "이렇게 보인다"까지만 말한다. 저장된 값과 화면 값(data-* 속성, 화면 낭독 글)을 나란히 적으면 "왜 그렇게 보이는가"까지 말한다. -> Step 3
3. 표시는 화면 안에서 그린다. 좌표를 눈대중으로 넣으면 거의 항상 한 열이나 한 행씩 밀린다. 브라우저 화면이면 요소를 글자나 셀렉터로 찾아 테두리와 번호를 그 자리에 그리고 찍는다. -> Step 4
4. 설명하려고 얹은 것이 설명 대상을 덮으면 안 된다. 하이라이트 라벨을 화면 위에 직접 올리면 거의 항상 무언가를 가린다. 제목, 입력칸 라벨, 옆 열의 값이 덮인다. 이미지에는 번호만 두고 설명은 캡션으로 뺀다. 번호 배지는 작아서 어디에 놓아도 손실이 적다. -> Step 4
5. 만든 것은 반드시 눈으로 본다. 도구가 성공을 반환했다는 것은 파일이 써졌다는 뜻일 뿐이다. 테두리가 엉뚱한 요소에 갔는지, 배지가 내용을 덮었는지, 이음매에 머리줄이 반복됐는지, 건넨 링크에서 이미지가 깨졌는지는 열어 봐야 안다. -> Step 5·6
6. 찍은 것과 못 찍은 것을 가른다. 코드로는 확인했지만 데이터에 사례가 없어 화면으로 못 보인 것은 "(코드 근거)"로 따로 단다. 섞으면 찍은 것의 무게까지 의심받는다. -> Step 1·3

정책

정책	언제 걸리나	내용
데이터와 설정은 읽기만, 바꾸려면 묻는다	Step 3	사례를 찾는 쿼리는 자유다. 사례를 만들려고 개발 DB 를 바꾸는 것은 사용자 확인 뒤에만 하고, 바꾼 값을 적어 두었다가 되돌린다. 운영 DB 는 어떤 경우에도 대상이 아니다
찍으면서 바뀐 것은 문서와 보고에 적는다	Step 3 · Step 6	로그인 세션 생성, 외부 로그인 동의, 개발 DB 변경처럼 찍는 과정에서 생긴 흔적
받는 사람이 열 수 있는 형태로 건넨다	Step 6	로컬 경로는 받는 사람 기기에서 안 열린다. report.html 파일을 보내거나 링크를 만들고, 링크면 실제로 열리는 것을 확인한 뒤 건넨다
바깥으로 보내는 것은 확인받는다	Step 6	슬랙, 메일, 고객 전달은 초안으로 둘지 바로 보낼지 먼저 묻는다

전제

전제	확인	없으면
작업이 화면에 드러난다	바뀐 것이 사용자가 보는 화면에 나타나나	백엔드나 스크립트만 바뀐 작업은 대상이 아니다. 글로 보고한다
찍을 제품이 떠 있다	로컬 개발 서버나 스테이징 주소가 응답하나	띄우는 법은 그 저장소의 문서를 따른다. 이전 코드는 axes §시간축
브라우저 도구가 있다	node scripts/shot.mjs 가 Playwright 로 돈다. 다른 도구도 페이지에서 JS 를 실행할 수 있으면 된다	Playwright 설치와 다른 도구로 찍는 법은 capture §브라우저 조작
로그인할 수 있다	로그인해야 보이는 화면인가, 계정이 있나	capture §로그인 상태 만들기
Python Pillow	python3 -c "import PIL"	이어 붙이기와 잘라 내기가 안 된다

절차

0. 질문과 축     READ <- variants/axes - 축마다 준비하는 일이 다르다(코드 되돌리기, 데이터 바꾸기, 문서 읽기, 사례 찾기). 고른 축의 절만
1. 항목과 판정   (점검축이면 axes §점검축 1~2 가 항목을 만든다)
2. 구조          READ <- steps/20-document - 항목을 절로 묶는 기준, 판정 어휘, 요약, 그림과 표의 자리
3. 찍기          READ <- steps/30-capture - 로그인, 합성 이벤트, 긴 화면, 화면 값 읽기에서 막힌다
4. 표시          READ <- steps/30-capture §화면 안에서 그리는 표시 - 좌표를 재면 한 열씩 밀린다
5. 이미지 확인   (여는 문서 없음. 확인 목록은 Step 5 안에)
6. 내기          READ <- steps/60-output - 템플릿을 깨면 좁은 화면과 인쇄가 무너지고, 결정 블록 규칙을 어기면 복사한 묶음이 잘린다

Step 0. 질문과 축

한 문장으로 적는다. "이번 주에 고친 것을 고객에게 설명한다", "기획서 대비 무엇이 남았는지 기획자와 정한다"처럼 받는 사람과 목적이 함께 들어가야 한다. 목적이 다르면 같은 화면이라도 무엇을 강조할지가 달라진다. 그 다음 목적 절의 표에서 축을 고르고 axes 의 그 절을 읽는다.

끝나면 질문 한 문장, 축, 받는 사람이 정해져 있다.

Step 1. 항목과 판정

캡처부터 시작하지 않는다. 이번 문서에서 다룰 것을 항목으로 적고, 각각에 참조 코드와 판정을 단다. 이 목록이 문서의 뼈대가 되고, 캡처할 화면과 표시할 지점도 여기서 정해진다.

참조 코드는 성격이 다른 것끼리 접두어를 나눈다. 받는 사람의 관심이 다르기 때문이다.

• 요청받아 한 일은 R-1, R-2 ... (된 건가가 궁금하다)
• 하다가 발견해 함께 고친 것은 A-1, A-2 ... (왜 건드렸나가 궁금하다)
• 명세 대조에서 어긋난 것은 G-1, G-2 ... (어떻게 할 건가가 궁금하다)
• 점검의 발견은 묶음 번호를 따른다 1-1, 1-2 ... (원인이 같은 것끼리)

판정 어휘는 문서 전체에서 한 벌로 통일한다(어휘 예는 document §판정 어휘). 판정은 세어서 첫 장에 올린다. "35개 구현, 3개 판단 필요, 1개 결함" 한 줄이 문서 전체를 대신한다. 세다 보면 목록의 빈 곳도 드러난다.

작업 중 고친 것을 빠뜨리기 쉬우니 git log 를, 명세 대조라면 원문을 한 줄씩 훑어 목록을 채운다. 항목마다 화면으로 보일 수 있는지(사례가 데이터에 있는지)도 이때 표시해 둔다. -> 핵심 원칙 6

끝나면 항목마다 코드, 판정, 찍을 화면 또는 "(코드 근거)"가 붙어 있다.

Step 2. 구조

절은 목차에서 고르는 것이 아니라 항목을 묶다 보면 생긴다. 묶는 기준은 넷 중 하나다.

• 화면별 - 한 화면에 여러 항목이 몰려 있을 때. 개선 보고의 기본이다
• 판정별 - 판정이 갈릴 때. 대조 보고의 기본이고, 받는 사람이 "정할 것"만 먼저 보게 된다
• 원인별 - 발견이 많고 화면 여러 곳에 흩어질 때. 점검 보고의 기본이다
• 항목별 - 항목 하나하나가 독립된 결정일 때. 의사결정문의 기본이다

어느 쪽이든 앞에는 한 장으로 전체를 말하는 요약을 두고, 뒤로 갈수록 상세해진다. 받는 사람이 위에서부터 읽다가 언제든 멈춘다고 가정한다. 절 수는 보여 줄 것에 따라 정한다. 억지로 채우지 않고, 빈 절은 만들지 않는다. 구조를 짜는 구체적인 방법과 실제 예는 document 에 있다.

Step 3. 찍기

축에 따라 준비가 다르다(axes). 공통으로 지킬 것만 여기 적는다.

• 겹쳐 볼 짝은 같은 뷰포트, 같은 스크롤 위치, 같은 범위로 찍는다. 그래야 두 장이 픽셀 단위로 맞아 슬라이더와 차이로 볼 수 있다(60-output §겹쳐 보기)
• 비교하는 화면끼리는 같은 데이터를 넣는다. 데이터가 다르면 비교가 성립하지 않는다. 한 사실이 화면마다 다르게 보이는 것을 보일 때는 같은 레코드로 그 화면들을 다 찍는다
• 보여 줄 기능에 필요한 데이터가 실제로 있는지 캡처 전에 쿼리로 확인한다. 빈 화면을 찍어 놓고 나중에 발견하면 스택을 다시 세워야 한다
• 로그인 상태를 확인하고 찍는다. 로그인해야 보이는 요소를 로그아웃 상태에서 찍고 "없다"고 적는 실수가 실제로 나온다. 없다고 판정하기 전에 그것이 정말 없는 것인지, 지금 세션에 안 보이는 것인지를 가른다
• 같은 순서로 조작한다. 촬영 목록을 한 파일로 만들어 두면 다시 찍을 때 그 파일만 돌린다
• 뷰포트는 넉넉하게 잡는다. 화면 아래가 잘리면 다시 찍어야 한다
• 저장된 값과 화면 값을 함께 읽어 둔다. -> 핵심 원칙 2
• 어떻게 그 화면에 닿았는지 함께 적어 둔다. 경로와 걸음 수를 나중에 되짚으려면 다시 들어가 봐야 한다. 찍는 김에 적으면 공짜다(document §화면의 자리와 깊이)

조작에서 자주 막히는 지점은 capture 를 본다.

Step 4. 표시

브라우저 화면이면 scripts/shot.mjs 로 찍는 순간 화면 안에 테두리와 번호를 그린다(-> capture §화면 안에서 그리는 표시). 긴 화면은 나눠 찍어 scripts/stitch.py 로 잇고, 사이드바처럼 논점 밖인 부분은 같은 스크립트로 잘라 낸다. 브라우저가 아닌 화면만 grid_overlay.py 로 좌표를 읽어 annotate.py 로 그린다.

• 테두리는 강조할 요소만 감싼다. 넓게 잡으면 무엇을 보라는 것인지 흐려진다
• 색은 판정에 맞춰 한 벌로 정한다. 문서를 넘길 때 색만으로 성격이 읽힌다. 개선 전과 문제 지점은 붉은색, 개선 후는 초록색이 기본이고, 대조 보고라면 없는 것은 붉은색, 있는 것은 초록색, 판단 필요는 주황색이 된다
• 비교하는 두 화면의 표시는 각각 찾는다. 텍스트 길이가 달라 레이아웃이 미세하게 움직인다
• 모든 촬영과 표시를 파일 하나에 모은다. 표시를 고칠 때마다 전부 다시 만들게 되고, 나중에 화면을 다시 찍을 때도 그 파일만 돌리면 된다

Step 5. 이미지 확인

Read 도구로 전부 연다. 확인할 것:

• 표시 결과 줄에 NOT FOUND 가 없는가
• 테두리가 강조 대상을 정확히 감쌌는가. 같은 글자의 다른 자리(다른 표의 같은 열 이름)를 물지 않았는가
• 번호 배지가 글자나 막대 칸을 덮지 않았는가
• 이음매에 머리줄이나 목차가 반복되지 않았는가
• 잘라 낸 위쪽에 제목이 반쯤 걸치지 않았는가. 나란히 놓을 두 장의 비율이 지나치게 다르지 않은가
• "없다"고 쓴 것이 화면에 정말 없는가. 로그인 상태나 조건 때문에 안 보인 것이면 판정을 뒤집어야 한다
• 캡션이 말하는 것과 사진이 보여 주는 것이 같은가. 그 폭에서 숨은 열을 "세 번 반복"이라고 쓰지 않았는가

어긋난 것을 고치고 다시 확인한다. 한 번에 맞는 경우는 드물다.

Step 6. HTML 과 전달

1. assets/web-report.html 을 보고서 폴더의 index.html 로 복사해 채운다. 골격과 카드 모양은 60-output 골격.
2. 받는 사람이 정할 것이 있으면 그 근거 카드 바로 아래에 결정 블록을 둔다. 막대의 복사 를 누르면 정한 것만 Markdown 으로 묶여 대화에 붙여 넣을 수 있다(60-output 결정 받기).
3. 세 보기를 연다. 넓은 화면, 390px 폭, scripts/check_print.sh 가 뽑은 인쇄 쪽 전부(60-output 화면과 인쇄).
4. inline-images.py 로 report.html 한 장으로 묶는다. 파일을 그대로 보내거나 링크로 내보내고, 받는 사람이 여는 방식 그대로 열어 확인한다(60-output 건네기).

템플릿의 <style> 을 보고서마다 고치지 않는다. 폭을 px 로 박거나 표를 .tw 밖에 두면 좁은 화면이 깨진다. -> 핵심 원칙 5

끝나면 report.html 이 세 보기에서 깨지지 않고, 받는 사람이 여는 방식으로 열리며, 보내는 일은 사용자 확인을 기다린다.

자주 막히는 곳

증상	원인과 대응
개발 서버가 곧바로 죽는다	next dev 는 stdin 을 읽는다. < /dev/null 을 주면 즉시 EOF 로 정상 종료된다. tail -f /dev/null | exec ... 로 stdin 을 열어 둔다
팝오버나 드롭다운이 안 열린다	Radix 등은 합성 이벤트에 반응하지 않는다. dispatchEvent 말고 자동화 도구의 실제 click 을 쓴다
전체 페이지 캡처가 같은 화면을 반복하거나 고정 머리줄이 겹친다	도구의 전체 페이지 캡처가 창이나 안쪽 상자를 못 내린다. shot.mjs 의 full 로 나눠 찍고 잇는다
이어 붙인 사진에 목차가 반복된다	고정 요소가 남았다. 논점 구간만 찍거나 잘라 낸다
휴대폰에서 표나 그림이 화면 밖으로 나간다	표를 .tw 로 안 감쌌거나 인라인 style 에 px 폭을 박았다. 템플릿의 클래스만 쓴다
표시가 엉뚱한 표를 가리킨다	같은 글자가 화면에 여럿이다. nth 를 바꾸거나 exact, 셀렉터로 좁힌다
엉뚱한 탭이 찍힌다	다른 세션이 브라우저 데몬을 공유하고 있다. 세션을 격리한다
있는 기능을 없다고 적었다	로그아웃 상태나 조건이 안 맞는 상태에서 찍었다. 판정 전에 로그인과 조건을 확인한다
링크로 열면 이미지 몇 장이 빈다	간이 서버가 동시 요청을 놓친다. inline-images.py 로 파일 하나로 묶는다
그림이 프레임 안에서 작게 나온다	높이 제한에 걸려 축소된 것이다. 세로로 긴 이미지는 좌우 2단 배치로 바꾸면 커진다
변경이 너무 미묘해 보인다	비교 대상을 잘못 골랐다. 목록 화면에서 컬럼명 하나 바뀐 것보다, 그 값을 실제로 편집하는 수정 화면을 보여 주는 편이 낫다
표가 빽빽해 읽기 어렵다	라벨을 왼쪽에 세우고 내용을 오른쪽에 두는 항목 목록으로 바꾼다. 그룹이 있으면 그룹 라벨을 행 왼쪽에 한 번만 둔다
문서가 고칠수록 길어지기만 한다	새 절을 만들었으면 그 내용을 담고 있던 기존 서술을 걷어낸다

공통 메커니즘

스크립트	무엇	내는 것
scripts/shot.mjs	촬영 목록대로 Playwright 로 화면을 열고, 표시를 그리고, 찍는다. 긴 화면은 나눠 찍는다	출력 폴더의 png, 표시 결과 한 줄씩
scripts/mark.js	페이지 안에서 요소를 글자나 셀렉터로 찾아 테두리와 번호를 그린다. shot.mjs 가 쓰고, 다른 브라우저 도구에서는 eval 로 넣는다	표시 결과 한 줄씩
scripts/stitch.py	나눠 찍은 조각을 잇고, 이름별 좌표로 잘라 낸다	출력 폴더의 png, 크기 한 줄씩
scripts/inline-images.py	HTML 의 상대 경로 이미지와 스크립트를 넣어 파일 하나로 만든다	report.html, 포함한 파일 수와 크기
assets/decisions.js	결정 블록을 저장하고, 화면 아래 막대의 복사 버튼으로 정한 것만 Markdown 으로 묶어 복사한다	고정 막대, localStorage
assets/compare.js	.pair[data-compare] 위에 나란히, 슬라이더, 차이 막대를 단다. 방식은 페이지 전체 상태 하나이고 기본은 슬라이더다. 두 그림의 픽셀 크기가 다르면 겹쳐 보기를 끈다	비교 막대, 차이 비율
assets/report-nav.js	h2·h3 로 왼쪽 목차를 세우고 분량(절·사진·결정·읽기 시간), 읽은 절, 남은 결정, 지금 위치를 보여 준다. 다시 열면 이어 보기	왼쪽 목차(좁으면 서랍), localStorage
scripts/serve-tailscale.sh	Tailscale 을 쓰는 환경에서 폴더를 tailnet 안 HTTPS 주소로 내보내고 응답을 확인한다(선택)	URL, PID, 내리는 명령
scripts/check_print.sh	브라우저 인쇄와 같은 경로로 확인용 A4 PDF 를 임시 폴더에 뽑는다	PDF 경로, 쪽수, 쪽마다 PNG
scripts/grid_overlay.py · scripts/annotate.py	브라우저 밖 이미지에 좌표 격자를 얹고, 박스와 범례를 그린다	주석 이미지

쓰는 법과 주의는 각 스크립트의 헤더 주석에 있다.

산출

보고서 폴더 하나(<날짜>-<주제>/): 고칠 때 쓰는 index.html, 이미지 images/(원본은 images/raw/), 촬영 목록과 잘라 내기 좌표 파일, 건네는 report.html(이미지 포함 한 장). 건넬 때는 링크와, 찍으면서 바꾼 것, 화면으로 못 보인 항목을 함께 말한다.

스킬 생태계에서의 위치

• 브라우저 도구 - 이 스킬은 고른 도구로 무엇을 어떻게 찍어 문서에 싣는지다. 도구를 고르고 세션을 격리하는 규칙이 환경에 따로 있으면 그것을 따른다
• 문서 스킬 - 화면 없는 보고서, 제안서, 슬라이드는 이 스킬이 아니라 일반 문서 스킬의 몫이다
• 글 다듬기 - 보고서 문장과 화면 구성을 다듬는 기준이 환경에 있으면 그것을 쓴다. 점검축에서 원칙의 출처가 되기도 한다