0002. 프로젝트 config가 정본: 렌더러가 읽는 파라미터 전부를 주석과 함께 둔다

• 상태: 채택 (재검토: 로드맵 게이트 G0)
• 날짜: 2026-08-13 (정리 2026-10-08)

배경

번들의 metadata/metadata.yaml에는 이미 plot_params가 들어 있는 경우가 많다. 그래서 config에는 바꾸고 싶은 키(예: 제목)만 적고 나머지는 번들 값에 맡기고 싶어진다. 그러나 그러면 그림을 조정할 때 raw_data/ 아래 잊기 쉬운 파일을 봐야 하고, config만 읽어서는 그림이 어떤 값으로 그려지는지 알 수 없다. 사용자는 Case B 반입(DE + GO 번들 프로젝트)에서 이 방식을 바로잡았다. 연구자는 Python을 읽지 않고 config만으로 그림을 이해하고 조정해야 한다(config = 연구자 UI).

결정

• 반입하는 모든 그림의 plots.<name> 블록에는 렌더러가 읽는 키 전부를 쓴다(색, 임계값, 축 범위, 컬러맵, 크기, top_n, 정렬·주석 방식 ...). 번들 값과 같아도 쓴다.
• 각 키에는 역할·단위·조정 방향 주석을 단다(AGENTS.md §1.6).
• 병합 순서 bundle < style preset < config는 유지하지만, 사용자가 조정할 만한 값을 번들 값에 맡기지 않는다.

결과

• config 하나로 그림의 모든 값을 보고 바꿀 수 있다. 대가로 config가 길어진다(paper config 158–737줄).
• 손으로 복사하지 않게 도구가 대신한다.
• fa ingest bundle: 번들 값과 스키마 기본값으로 블록 전체를 주석과 함께 쓴다.
• fa param scaffold: 렌더러의 전체 블록을 출력한다.
• fa param sync --apply: 빌드가 기본값으로 대신한 키를 채운다.
• fa lint: 빠진 키, 안 읽힌 키, 오타를 찾는다.
• 렌더러 SCHEMA가 키의 기본값과 설명을 한 곳에 둔다. tests/test_renderer_schemas.py가 스키마와 코드가 일치하는지 확인한다.
• 게이트 G0: 도구가 안정되면 "기본값과 다른 키만 config에"(정책 A)로 바꿀지 다시 정한다. 바꾸면 이 기록을 대체한다.