coding-agent skill · MIT

관찰이 수정보다 먼저다.
코드를 고치기 전,
진짜 플로우를 본다.

레거시 웹 기능을 고치거나 디버깅하기 전, 실제 사용자 플로우를 브라우저부터 DB까지 한 줄의 증거 체인으로 추적해 기록한다.

Trace the real legacy-web user flow — browser, API, business rule, database — before you touch a line of code.

GitHub Repo → promptbox 목록

legacy-web evidence-chain browser-to-db playwright chrome-devtools debugging claude-code

01 · 왜 필요한가

왜 필요한가 why this exists

유닛 테스트는 통과하는데

실제 화면에선 여전히 안 된다. 브라우저 관점의 증거가 없으면 빈틈을 못 본다.

⬡

HTTP 200이 정상을 뜻하지 않는다

성공 상태 코드 뒤에 비즈니스 예외나 잘못된 분기가 숨어있을 수 있다.

◈

엔드포인트 이름으로 DB 동작을 추론하면 위험

하나의 API가 3개의 쓰기를 트랜잭션 없이 수행할 수 있다. 코드를 추적하거나 런타임을 봐야 한다.

⟳

레거시 플로우는 얽혀있다

리다이렉트, 재시도, 폴링, 백그라운드 호출이 결과에 영향을 준다. 단일 API 로그로는 못 잡는다.

02 · 핵심 원칙

핵심 원칙 prime directive

관찰이 수정보다 먼저다. 현재 동작이 증거로 표현되거나, 접근 불가능한 증거 원천이 명시되기 전에는 구현을 시작하지 않는다.

최소한 다음을 확립한다:

순서가 있는 사용자 액션과 브라우저 요청
비즈니스 동작을 선택하거나 변경하는 요청 필드
관련된 클라이언트 상태 전환
프론트엔드 콘솔과 백엔드 비즈니스 예외 증거
선택에 사용되는 DB 읽기와 플로우가 유발한 쓰기 / 사이드 이펙트

03 · 브라우저 → 데이터

브라우저 → 데이터 체인 browser-to-data chain

한 번의 클릭이 끝까지 어떻게 이어지는지 추적한다. 한 단계도 건너뛰지 않는다:

user action trigger

↓

DOM event / handler

↓

validation & client store

↓

API client

↓

gateway / controller

↓

application / domain service

↓

business rule or exception

↓

transaction

↓

repository / query

↓

database reads / writes

↓

event · cache · audit · downstream

↓

response

↓

client state / render result

04 · 워크플로

10단계 워크플로 the workflow

플로우 정의 & 레코드 시작 — 목표, 사용자 역할, 환경, 진입 URL, 증상, 안전 경계, 사용 가능한 증거 원천 정리
첫 액션 전 베이스라인 캡처 — 네트워크 / 트레이스 / 콘솔 녹화를 재현보다 먼저 시작
정확한 사용자 여정 재현 — 한 액션씩. 모든 결과 요청 (redirect · retry · poll · background 포함) 을 순서대로 기록
브라우저 → 데이터 체인 구축 — 상태 변경 · 선택이 중요한 모든 요청에 대해 진입점, 분기 필드, 비즈니스 규칙, 읽는 테이블, 쓰는 테이블, 트랜잭션 경계 식별
병렬 분석 (브라우저 상태 보존) — 브라우저 소유자 1명, 프론트 / 백엔드 / 데이터 / 어드버사리얼 역할 분담
최초 분기점 찾기 — 가장 먼저 틀어진 단계에서 멈춘다. 이후 오류는 결과일 뿐
반박 가능한 가설 — Observed fact · Inference · Disproof check · Proposed change
점진적 구현 — 회귀 테스트 우선, 최소 파일만 변경, 로깅은 진단에 기여하게
같은 플로우로 재현 — 동일 role · input · 시작 상태로 before / after 비교
증거 레코드 마무리 — 검증된 현재 플로우, 목표 플로우, 최초 분기, 변경 파일, 테스트, before / after, 남은 가정

05 · 증거 수준

증거 수준 evidence levels

모든 주장은 수준을 명시한다. 코드 추론을 프로덕션 행 변경 증거로 둔갑하지 않는다.

runtime verified test verified code inferred assumed unavailable

수준	의미	허용되는 근거
`runtime verified`	재현 플로우에서 관찰됨	브라우저 트레이스, 콘솔, 백엔드 로그, 승인된 쿼리, APM
`test verified`	자동화 테스트로 재현됨	테스트 출력과 단정문
`code inferred`	실행 코드 경로로 강하게 함축됨	소스 경로, 심볼, SQL / repository 매핑
`assumed`	그럴듯하지만 검증 안 됨	명시적 가정 + 반박 검사
`unavailable`	필요한 원천에 접근 불가	누락 접근 메모 + 대체 증거 사용

06 · 도구

브라우저 도구 라우팅 browser tool routing

우선순위	도구	역할
1차	`Playwright CLI`	컴팩트 재현 · 트레이스 · 요청 순서 캡처 (기본 도구)
2차	`Chrome DevTools MCP`	정밀 검사 · 에스컬레이션 (정확한 body · 소스맵 · 성능)
옵션	`Ego Lite`	공유 로그인 상속이 하드 제약일 때만
옵션	`agent-browser`	이미 표준화된 repo에서만, 네비게이션 캡처 한계 검증 후

상세 결정표와 운용 시퀀스는 repo의 references/BROWSER-TOOL-ROUTING.md 참조.

07 · 설치

설치 install

git clone https://github.com/cskwork/web-legacy-compass.git
cd web-legacy-compass
./install.sh /path/to/your/project

SKILL.md, references/, templates/ 가 <project>/.agents/skills/web-legacy-compass/ 로 복사되고, docs/web-flows/ 디렉토리가 생성된다.

구조

.
├── SKILL.md                          # 스킬 정의 (frontmatter + 워크플로)
├── references/
│   ├── BROWSER-TOOL-ROUTING.md       # 도구 결정표
│   ├── EVIDENCE-MODEL.md             # 증거 수준 · 페이로드 규칙 · DB 매핑 · 로깅
│   └── SUBAGENT-PATTERN.md           # 병렬 에이전트 패턴
├── templates/
│   └── FLOW-RECORD.md                # 13섹션 조사 레코드 템플릿
└── install.sh

08 · 완료 기준

완료 게이트 completion gate

다음이 모두 참이 되기 전에는 완료를 선언하지 않는다:

각 사용자 액션이 순서 있는 요청 (또는 요청 없음) 에 매핑됨
redirect · retry · poll · duplicate · background 호출이 모두 처리됨
중요한 요청 / 응답 필드가 기록되고 비밀은 마스킹됨
클라이언트 상태 전환과 콘솔 증거가 시퀀스 ID에 매핑됨
백엔드 비즈니스 예외와 기술 장애가 분리되어 플로우에 연결됨
선택 중요 DB 읽기와 상태 변경 연산이 코드 / 런타임 증거에 매핑되거나 unavailable 표시
트랜잭션 경계와 캐시 / 이벤트 / audit / 다운스트림 사이드 이펙트가 문서화됨
runtime 사실이 code 추론 및 가정과 구분됨
최초 분기점이 증거로 뒷받침되고 반박 검사를 가짐
구현이 최소이고 회귀 테스트되었으며 실제 브라우저 플로우로 재현됨
최종 Markdown 레코드가 구현된 동작과 일치함

관찰이 수정보다 먼저다.코드를 고치기 전,진짜 플로우를 본다.