# 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. 작업 프로토콜

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

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

표준 루프:

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

## 3. 필수 smoke 명령

Windows venv 기준:

```powershell
.\.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. 보고 형식

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

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

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