Domain Expert

문서 작성 완결성 체크리스트

문서 태스크 수행 시 제출 전 반드시 확인:

1. 트리 다이어그램 정합성: 프로젝트 트리 작성 시 실제 파일시스템과 대조하여 누락 파일이 없는지 확인. 반드시 숨김 디렉토리를 포함하여 탐색할 것 — fd -H -t f 또는 eza -a --tree 사용 (ls -R 단독 사용 금지: .claude-plugin/ 등 dot-prefix 디렉토리 누락 위험)
2. 플레이스홀더 표시: 미완성/템플릿 상태인 파일은 "(placeholder)" 또는 "(template)"로 명시
3. 알려진 이슈 주석: 오타, 의도적 명명, 미완성 부분 등은 주석으로 이유를 기록 (예: referrences/ 디렉토리명)
4. 데이터 교환 포맷: 에이전트/컴포넌트 간 데이터 교환이 있으면 YAML 스키마 또는 구조 설명 포함
5. 커스터마이징 가이드: 도메인 추가, 설정 변경 등 확장 절차가 필요하면 포함 여부 판단
6. Critical Claim 교차 검증: "0% 준수율", "전면 누락", "모든 X가 Y" 등 극단적 주장(0%/100%)을 기술하기 전에 반드시 파일 직접 확인으로 교차 검증할 것. 검증 명령 예시: fd -H -t f "plugin.json" — 발견 시 주장을 즉시 수정
7. Single-pass 문서 작성: 분석 보고서·매트릭스 등 구조화 문서는 반드시 Write 도구 1회로 완성된 내용을 한 번에 작성. 중간에 Edit/append로 내용을 덧붙이는 방식 금지 — 중복 행·섹션 발생 원인 (ref-20260411T181500: gen-050 structure_quality 0.65). 작성 후 wc -l 검증 시 예상 줄 수와 크게 다르면 중복 여부 확인

문서 생성 패턴

분석 보고서를 생성할 때는 다음 순서를 따른다:

1. Draft-then-Write: 먼저 전체 내용을 컨텍스트 안에서 완성한 뒤 Write 도구로 한 번에 저장
2. 구조 검증 (의무): 저장 후 level-2 헤딩 수를 반드시 확인

   # ⚠ 반드시 '^## [^#]' 패턴 사용 — '^##'는 ### 서브섹션도 매칭하여 오탐 발생
   # (ref-20260411T185000: gen-051 AC5 FAIL 원인)
   grep -c '^## [^#]' <output_file>
   # Sprint Contract AC와 동일 패턴으로 검증 — 범위 밖이면 ### 제거 후 재작성
   

3. 중복 탐지 (의무 — 건너뛰기 금지): Write 직후 핵심 항목의 중복 여부를 반드시 확인

   # 분석 대상(플러그인·파일·항목) 중 첫 번째와 마지막 항목으로 검증
   grep -c '<first_item>' <output_file>   # 1 초과면 중복
   grep -c '<last_item>' <output_file>    # 1 초과면 중복
   # 중복 발견 시 Write 도구로 전체 재작성 (Edit 금지)
   

지식 기반 구조

domain/knowledge-base/
├── AGENTS.md          # 전체 목차 (이것만 읽으면 됨)
├── architecture/      # 시스템 아키텍처 문서
├── api-specs/         # API 명세
├── coding-standards/  # 코딩 표준
└── business-rules/    # 비즈니스 규칙

코드 구현 품질 가이드 (implementation task_type용, ref-20260411T205500)

코드를 생성하는 태스크에서 conciseness 및 structure_quality 점수를 유지하기 위한 규칙:

1. 300줄 상한 규칙: 단일 Python/JS 파일이 300줄을 초과할 것으로 예상되면, Sprint 설계 시점에 모듈 분리를 계획할 것.

   • CLI 도구: 서브커맨드별 모듈 + 공통 유틸리티 모듈로 분리
   • 예: memory_cli.py(611줄) → memory_cli.py(메인) + memory_capture.py + memory_query.py
   • (ref: gen-055 conciseness 0.65 — 단일 파일 CLI 병목)

2. Syntax 검증 의무: Write/Edit 후 Python 파일은 python3 -c "import ast; ast.parse(open('<file>').read())" 실행

3. 테스트 동반 권고: 주요 함수(argparse 서브커맨드 핸들러 등)에 최소 1개 테스트 작성 권고

배경: gen-054(scaffold, 0.88)와 gen-055(tool-impl, 0.73)의 15포인트 차이는 파일 크기/모듈화 차이가 주된 원인. scaffold 태스크는 자연히 높은 structure_quality를 얻지만, tool 구현은 의식적 모듈화가 필요하다.

Python 에러 핸들링 가이드 (implementation task_type용, ref-20260412T045500)

코드를 생성하는 태스크에서 failure_handling 및 resumability 점수를 유지하기 위한 규칙:

1. bare except 금지: except: pass / except: continue 대신 구체적 예외 타입 명시
   • 허용: except (OSError, UnicodeDecodeError): continue
   • 금지: except: continue — 모든 예외를 무음으로 삼킴 (디버깅 불가)
2. CLI 입력 경계 검증 필수: argparse 인자에 타입·범위·경로 검증 추가
   • 예: if not 0.0 <= args.min_confidence <= 1.0: parser.error("min-confidence must be 0~1")
3. 파일시스템 graceful degradation: 디렉토리/파일 부재 시 stderr 경고 후 계속
   • 예: if not d.exists(): print(f"[skip] {d} — not found", file=sys.stderr); continue
4. 누적 데이터 도구 (JSONL 로거 등): idempotent 재실행 설계
   • append-only 금지 — 동일 session_id 재기록 시 덮어쓰기 또는 skip 처리
   • 체크포인트 저장: 중간 결과를 별도 .checkpoint 파일에 기록하여 재시작 지원

배경: gen-057(0.83, Phase 4 MemFactory) — failure_handling 0.70 + resumability 0.75가 golden 0.85 미달 원인. 12/12 AC 전부 통과했지만 방어 코딩 패턴 부재가 NFR 평가 항목 감점.

라인 수 사전 추정 규칙 (implementation task_type용, ref-20260412T091200)

코드를 생성하는 태스크에서 cost_time_control 점수를 유지하기 위한 규칙:

1. Write 전 라인 수 사전 추정 필수: 각 파일의 예상 줄 수를 함수 단위로 계산한 뒤 목표 상한의 90% 이하로 설계
   • 예: 상한 ≤300줄이면 목표 구현 ≤270줄로 설계
   • 방법: 함수별 예상 줄 수 합산 (import 10 + 함수A 30 + 함수B 50 + ...) → 합계 확인
2. 오버슈트 시 재설계 (트리밍 금지): Write 후 줄 수 초과 시 Edit로 트리밍하지 말고 함수 설계를 축약하여 Write 1회로 재작성
   • 트리밍 Edit 반복은 cost_time_control 감점 원인 (ref: gen-058 82→80줄 2회 트리밍)
3. 함수 단위 공간 배분: 파일 내 각 함수/섹션에 예산(줄 수)을 미리 할당
   • 예: 300줄 파일 = imports(15) + 공통유틸(40) + 함수A(80) + 함수B(80) + CLI(60) + 여유(25)
4. 격리/패치 오버헤드 예약: 사후 패치가 예상되는 경우(테스트 격리 추가 등) 해당 줄 수를 사전 추정에 반영
   • 예: 테스트 격리 컨텍스트 매니저 추가 예상 → 대상 함수당 +2줄 선반영

배경: gen-058(0.82) — memory_utils.py 82→80줄(2회 트리밍), memory_cli.py 79→70줄 post-hoc 수정으로 cost_time_control 0.75. 사전 추정으로 방지 가능. gen-059(0.82) — 격리 패치 +2줄 미반영으로 capture 파일 73L→72L 목표 1줄 초과.

테스트 격리 설계 규칙 (testing task_type용, ref-20260412T101200)

테스트 코드 작성 시 프로덕션 시스템 오염을 방지하기 위한 규칙:

1. Write 전 격리 전략 결정 필수: 테스트 함수 설계 시 각 함수가 쓰기를 시도하는 경로를 파악하고, Write 전 격리 방법을 결정

   • 실제 파일시스템 쓰기 → tempfile.TemporaryDirectory 또는 patch
   • DB/네트워크 → unittest.mock.patch or pytest.fixture

2. module-level import된 상수 패치 위치: from module import CONST 패턴의 상수는 원본 모듈이 아닌 사용 모듈에서 패치

   • 올바름: patch('memory_capture.FACTS_DIR', Path(d))
   • 틀림: patch('memory_utils.FACTS_DIR', Path(d)) — 이미 바인딩된 참조에 영향 없음

3. 격리 실패 즉시 감지: 테스트 실행 후 프로덕션 디렉토리 파일 수를 확인하는 AC 추가 의무화

   • 예: find knowledge/30-memory/facts/ -name '*.md' | wc -l = 0

4. pytest stdin 격리 (gen-060): capture 함수 테스트 시 body='' 금지

   • pytest의 DontReadFromInput이 sys.stdin.read() 호출 시 OSError 발생
   • 해결: capture 함수에 body='x' 등 non-empty body 주입 필수

5. ExitStack extras 동적 패턴 (gen-060): 동적 수의 patch 조합 시 _env(tmp, extras=()) 헬퍼 사용

   • fake 파일 write는 ExitStack 진입 전 실행 (write_text 패치와 충돌 방지)
   • 기본 3개 patch + 선택적 추가 patch 조합에 적합

6. TEMPLATES_DIR 완전 격리 (gen-060): FACTS_DIR, EXPERIENCES_DIR 외에 TEMPLATES_DIR도 패치 필수

   • fake template 파일을 tempdir에 write_text로 생성 후 TEMPLATES_DIR 패치
   • 메모리 관련 테스트 시 모든 디렉토리 상수 격리 확인

배경: gen-059(0.82) — test_cmd_capture_success가 production vault(knowledge/30-memory/facts/)에 4개 아티팩트 생성. 사후 cleanup + 격리 패치 필요. test_isolation 0.75.
gen-060(0.88) — memory_capture failure_handling 강화에서 pytest stdin OSError, ExitStack 동적 패턴, TEMPLATES_DIR 격리 패턴 발견. test_isolation 0.95.

Sprint Contract 검증 명령어 규칙 (ai-058-02)

Evaluator의 자동 검증을 활성화하기 위한 Sprint Contract 포함 규칙:

1. verification_commands 항상 포함: Planner는 Sprint Contract에 실행 가능한 검증 명령어 명시

   • 예: python -m pytest knowledge/00-meta/tools/tests/ -v
   • run_verification_commands MCP가 이 필드를 읽어 Evaluator 자동 실행
   • 미포함 시: verification_commands_run: false → artifact_discipline 감점

2. working_directory 명시: 검증 명령어 기준 디렉토리를 절대경로로 포함

   • testing task_type은 항상 필수
   • 예: working_directory: /Users/urd_book/Projects/claudemate

배경: gen-058/060 모두 verification_commands_run: false — artifact_discipline 감점. Sprint Contract에 명시 시 자동 검증 활성화 가능. (ai-058-02 해소)

규칙 적용 우선순위

1. 안전 규칙 (security rules) — 최우선
2. 불변 비즈니스 규칙 (invariant business rules)
3. 코딩 표준 (coding standards)
4. 스타일 가이드 (style guide)

Level 3: Resources (필요 시 로드)

도메인 지식 업데이트 프로세스

도메인 지식이 부족하다고 판단되면:

1. data/reflections/에 지식 부족 기록 생성
2. 관련 문서 요청을 domain/knowledge-base/gaps.md에 추가
3. 다음 개선 루프에서 Meta Agent가 처리

MCP 도구 연동

도메인 MCP 서버(servers/harness-mcp-server.py)의 다음 도구를 활용:

• search_knowledge — 지식 기반 검색
• check_rules — 규칙 위반 검사
• get_golden_example — 골든 예제 조회