DMF_Crawler/AGENTS.md

DMF Crawler — AI Agent 작업 지침

이 파일은 이 저장소에서 일하는 모든 AI coding agent 의 진입 규칙이다.
자세한 근거/운영 체계는 docs/design/07-tdd-red-system.md 가 정본이다.

0. 먼저 읽을 문서

작업을 시작하기 전 반드시 다음을 읽는다.

1. docs/HANDOFF.md — 현재 상태/함정/미완 작업
2. docs/00-REQUIREMENTS.md — 사용자 요구 SSOT
3. docs/design/01-architecture.md — 아키텍처 SSOT
4. docs/design/07-tdd-red-system.md — TDD/RED/디자인 감사 SSOT
5. 작업 파일과 직접 관련된 설계 문서
   • 데이터/DB: docs/design/02-data-model.md
   • xlsx: docs/design/03-xlsx-report-spec.md
   • GUI: docs/design/04-onboarding-wizard.md
   • agy: docs/research/05a-agy-cli-ssot.md

1. 최상위 법칙 — No RED, No Code

• src/ 기능 코드는 실패하는 테스트(RED) 없이 작성하지 않는다.
• 테스트가 즉시 통과하면 RED 가 아니다. 왜 통과했는지 확인하고 더 강한 테스트로 바꾼다.
• RED 실패 로그를 본 뒤 최소 구현으로 Green 을 만든다.
• Refactor 는 관련 테스트가 Green 일 때만 한다.
• 테스트를 약하게 바꿔 Green 을 만들지 않는다.
• 실패를 숨기기 위한 skip, xfail, assert True, 광범위한 except: pass 는 금지다.

2. 작업 프로토콜

모든 코드 변경 전 짧게라도 다음을 정한다.

변경 파일:
사용자/운영 위험:
추가/수정할 RED:
먼저 돌릴 영향 테스트:
전체 smoke 명령:

표준 루프:

1. RED 작성
2. RED 실행 — 기대한 이유로 실패하는지 확인
3. 최소 구현
4. 영향 테스트 Green
5. Refactor(필요할 때만)
6. compile/import/CLI/pytest smoke
7. 남은 실패를 정직하게 보고

3. 필수 smoke 명령

Windows venv 기준:

.\.venv\Scripts\python.exe -m compileall -q src tests
.\.venv\Scripts\python.exe -m dmf_crawler --help
.\.venv\Scripts\python.exe -m dmf_crawler doctor --json
.\.venv\Scripts\python.exe -m pytest tests -q

네트워크/API 키가 필요한 테스트는 기본 smoke 에 넣지 않는다. fixture/mock 으로 대체하고, 실제 nedrug/API 호출은 사용자 승인 후 수동 smoke 로 분리한다.

4. 디자인 감사 RED 는 빡세게 한다

GUI/xlsx/report/UI 관련 작업은 기능 테스트만으로 끝내지 않는다. 다음을 RED 로 잡는다.

• 의미 없는 중앙 정렬, 시각적 치우침, 정렬선 붕괴
• 컨테이너 밖으로 나가는 텍스트/버튼/입력창
• 너무 작거나 대비 낮은 폰트
• 폼 label 누락, placeholder-only label
• input 내부 padding/버튼 간격/아이콘+텍스트 vertical alignment 오류
• 실제 입력 시나리오 누락(텍스트 입력, 붙여넣기, 버튼 클릭, 오류 표시)
• focus/tab order 문제
• 색만으로 상태 전달
• xlsx 시트 순서, 틀 고정, 자동필터, 내부 링크, 조건부서식, 팔레트 대비 누락
• 빈 상태/긴 한글/긴 경로/긴 API 키에서 깨지는 레이아웃

구체 기준은 docs/design/07-tdd-red-system.md 의 R4/R5 를 따른다.

5. RED 는 늘리기만 하지 않는다

테스트 스위트도 제품이다.

• 같은 위험을 중복 검사하면 통합한다.
• 구현 세부에 묶여 좋은 리팩터링을 막는 테스트는 행동 중심 테스트로 교체한다.
• flaky 테스트는 안정화하거나 계층을 낮춘다/올린다.
• 삭제/완화는 이유와 대체 커버리지를 기록해야 한다.

6. 이 프로젝트 고유 함정

• .ps1 은 UTF-8 with BOM 이어야 한다.
• .cmd 는 ASCII 만 사용한다.
• nedrug xlsx 는 openpyxl 로 읽지 않는다. sheet XML 직접 파싱.
• agy --json-schema 결과를 믿지 않는다. 자체 JSON 추출+검증.
• API 키/OAuth 토큰/웹훅/비밀번호는 로그·문서·저장소에 쓰지 않는다.
• 공공데이터포털 인증키는 선택이다. 키가 있으면 공식 API 최신 수집을 사용하고, 키가 없어도 기존 자료 리포트 생성·온보딩·스케줄 설치를 막지 않는다. source.mode=auto 에서 키가 없으면 AGY headful Chrome xlsx 수집을 먼저 시도한다.
• 수집용 AGY와 요약용 AGY를 구분한다. 수집용 AGY는 headful/visible Chrome 을 조작한다. 요약용 AGY는 사용자가 AI 요약을 켠 경우에만 headless/non-interactive 로 호출한다.
• Google 로그인은 선택이다. AI 요약 또는 browser 수집 모드를 사용자가 켠 경우에만 agy 설치/로그인을 안내하고, 기존 자료 xlsx 리포트를 막지 않는다.
• 비밀번호를 agy prompt 에 넣지 않는다. headful 수집 프롬프트에도 공공데이터포털 인증키/OAuth 토큰/비밀번호를 넣지 않는다.
• 수집 완결성 검증 없이 diff 하지 않는다.
• 같은 파일을 여러 agent 에게 동시에 맡기지 않는다.

7. 보고 형식

작업 완료 보고에는 반드시 포함한다.

변경 파일:
추가/수정한 RED:
RED 실패 확인:
Green 구현:
실행한 명령:
결과:
남은 실패/미검증:
디자인 감사 결과(해당 시):

“완성”이라고 말하려면 최소 compile/import/CLI/pytest smoke 결과가 있어야 한다. 안 돌렸으면 안 돌렸다고 말한다.