71 · 문서화 — 개발자

0. 개발자가 첫날 읽어야 하는 순서

1. ../NVR_ANALYSIS.md   이 저장소에 실제로 무엇이 있나
2. 02_도메인설계_영상저장장치.md          낱말의 뜻 (이것을 모르면 코드를 못 읽는다)
3. 00_아키텍처_4Layer.md             계층·박힘0·cfg 키 정본
4. 40_테스트설계.md                  무엇이 초록이어야 하나
5. 91_애자일계획…                    지금 무엇을 세우는 중인가

1. 절대 규약 여섯 — 어기면 빌드·검사가 막는다

# 규약 장치
1 L2 는 바깥을 모른다 — os·open·소켓·시계·난수 금지 verify/layer_audit.py · cmake nvrc_find_clock
2 값을 코드가 정하지 않는다 — 전부 ac() verify/hardcode_audit.py
3 ac() 에 기본값 인자가 없다 계약(00 §3)
4 새 키는 00 §8 에 먼저 적는다 verify/cfg_keys.py(양방향)
5 캐시에 쓰는 자리는 하나 ConsumerSink 토큰
6 없는 것을 있다고 적지 않는다 문서 마지막 절 · verify/req_trace.py

★★★ 2 번이 이 계보의 이름값이다. 「빠른 결과를 보이려고 값을 하나 박는」 순간 나자레 애자일 위반이고, 그것이 가장 자주 일어나는 실수다.

2. 코드 자리 (세울 자리)

nvrpipe/
  layers/
    l1_infra/    config.py bus.py cache.py store.py remote.py watch.py engine.py
                 siblings.py extract.py objdb.py vecdb.py embed.py vcs.py archive.py
                 ainsbus_backend.py delegate.py
    l2_domain/   genome.py locus.py transcript.py codon.py ribosome.py express.py
                 senses.py assembly.py sets.py space3d.py superpose.py corpus.py
                 lesson.py capsule.py generation.py lineage.py council.py blueprint.py
                 reach.py catalog.py determinism.py sink.py
    l3_app/      harvest_service.py transcribe_service.py express_service.py
                 learn_service.py assemble_service.py space_service.py
                 catalog_service.py archive_service.py council_service.py
                 blueprint_service.py consumer_sink.py
    l4_present/  main.py web/ gtk/ qt5/ glx/
  cpp/           engine/ faces/ CMakeLists.txt
  tests/         test_unit_* test_integration_* test_system_* test_parity_*
  verify/        run_all.sh layer_audit.py hardcode_audit.py cfg_keys.py
                 secret_audit.py doc_links.py req_trace.py probe_gate.sh
                 faces.sh golden.sh standalone.sh gen_conf_example.py
  config/        nvrpipe.conf.example   ← 손으로 고치지 않는다(생성물)
  docs/          이 문서들

★ 패키지 최상위가 layers 가 아니다 — 형제와 같은 이름을 쓰면 한 프로세스에 둘을 못 올린다(교훈 ⓕ).

3. 새 기능을 더하는 순서 — 여섯 단

1. 요구를 찾는다        readme 의 어느 줄인가 → 90_요구대응표에 줄을 잇는다
2. 낱말을 정한다        02 의 도메인 낱말과 어긋나지 않는가
3. 키를 적는다          00 §8 에 키를 더한다 (값이 아니라 키)
4. 검사를 먼저 쓴다     없는 것·틀린 것을 재는 검사부터
5. L2 → L1 → L3 → L4   아래서 위로
6. 대조군을 확인한다    강제를 꺼 보면 붉어지는가

★★ 3 번을 건너뛰면 verify/cfg_keys.py 가 잡는다 — 정본에 없는 키를 부르면 붉다. 그리고 정본에 있는데 아무도 안 부르는 키도 붉다(설계가 앞서간 자리를 세어 둔다).

4. 자주 틀리는 자리 일곱 (형제들의 실측)

함정 무엇이 일어나나
L2 에서 dict 순회를 산출에 삽입 순서가 산출을 가른다
hash() 사용 PYTHONHASHSEED 에 따라 실행마다 다르다
빈 env 가 파일을 가린다 「설정했는데 안 먹는다」(6tier)
접두를 두 번 붙인다 NVRPIPE_NVRPIPE_…
못 읽은 것을 빈 값으로 「같다」와 「안 봤다」가 섞인다
낡은 실행물로 검사 고친 것이 반영 안 된 채 초록(형제 공여 ⓐ)
부동소수 반올림 길 round() 와 nearbyint 가 .5 에서 갈린다

5. 커밋·이력

규약 왜
core.quotepath false 먼저 한글 397/399 다 — 안 끄면 이력이 escape 로 찬다(12 §2)
산출물을 커밋하지 않는다 build/·말뭉치·임베딩·세대
문서와 코드를 같은 커밋에 문서가 낡는 가장 흔한 까닭이 「나중에 고치기」다
2.2 GB 자료를 넣을지는 사람이 정한다 12 §1 — 되돌리기 어렵다

6. 지금 선 것 · 아직 없는 것 (2026-09-25 · 스프린트 1 뒤)

선 것 자리
ac() 계약 nvrpipe/layers/l1_infra/config.py
결정론 nvrpipe/layers/l2_domain/determinism.py
관문 여덟 verify/{layer_audit,hardcode_audit,cfg_keys,secret_audit,doc_links,req_trace,gen_conf_example}.py · verify/probe_gate.sh
일괄 검증 verify/run_all.sh — 초록·붉음·건너뜀 세 수
설정 보기 config/nvrpipe.conf.example — 생성물(278 키 · 값 0)
버전관리 개시 verify/git_init.sh · core.quotepath=false
검사 tests/ 77 통과(유닛 43 · 대조군 34)