56a6e2da93
- src/dist 산출물 분리 원칙 정리(.gitignore, .gitattributes) - 루트 및 주요 폴더(config/scripts/prompts/tests/src, 런타임 폴더 5종)에 안내용 README.md 추가 - CHANGELOG.md, LICENSE, docs/ops/05-release-and-versioning.md 추가 - docs/README.md 문서 지도 갱신
121 lines
5.2 KiB
Markdown
121 lines
5.2 KiB
Markdown
# 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 결과가 있어야 한다. 안 돌렸으면 안 돌렸다고 말한다.
|