cold-read 3회차(수정 세션 넷의 빈틈 9건), 통합·배치·문서 체계·번역 세션이 「매뉴얼에서 답을 못 찾았다」고 적은 곳, 프론트 총괄 교훈 둘, design-docs repo-structure 01·02·03의 「매뉴얼에 넣을 규칙」 중 백엔드 몫이 아직 매뉴얼에 없다. 세션마다 같은 판단을 스스로 다시 했다. 넣은 자리(항목별 표는 PR 본문): - delegate.md: upgrade 안내 「커밋:」 줄은 총괄이 합칠 때 적는다, 두 라운드 연속 결함이면 조사로, 병합 커밋에는 충돌 해결만, 자주 하는 실수 둘(충돌 없음은 merge-tree로, PR 만들기 전 head 브랜치의 PR을 API로). - improve.md: 절차 문서 결함과 대기 결함의 RED 모양, 테스트 Javadoc도 고친다, 그 코드를 지키는 lane 찾기, 두 라운드 연속 결함이면 조사로. - docs-writing.md: 문체·용어·언어 범위(코드 주석 제외), check-docs도 돌린다, 이동 커밋에 참조 수정을 같이, 번역 기준(영어 절 제목, 레지스트리 yaml, 머리말 없는 runbook, MANIFEST는 납품 당시 해시). - operate.md 4.1: zsh 파이프 rc와 자기 실행 멈추기, runner 사실(capacity 1, 12코어·31GB, 잠금 밖), 취약점 DB는 설치가 아니다, 형식은 나누기 전에. - reference/gates.md: 커밋하는 수정의 lockfile, 처음 켜진 lane의 이전 실패, lychee·buf·trivy 공식 이미지, smoke 이미지가 이 트리에서 만들어졌음, 원래 있던 실패 가리기(세 번), 순서 의존 재현, 공유 잠금 기다리기, 증거 실행의 --no-build-cache, 거짓 통과 두 줄(OOM 재시작, 조건 안 set -e), 새 7절 「workflow·검사 스크립트를 더할 때」. - reference/review-criteria.md: 관점 2·4·9·18·20·21·23·26·27의 볼 곳과 결함, Important 예시, leaf 변경 체크리스트(README 다섯 칸, 문서 검사). - reference/decisions.md: brief와 결정 원문이 다르면 원문, 취약점 DB 기본값. - reference/terms.md(새): 영어 그대로 쓰는 말과 「개발 환경」의 뜻. - README.md 2절(최상위 폴더는 큼), new-feature.md(테스트 환경·release/는 leaf 안), docs/ci-cd/template-vs-consumer.md(docs-check·link-check· check-repo-layout은 파생 서비스도 유지), settings-and-runtime 규칙. 버린 대안: 항목마다 따로 커밋(소유자 결정: 매뉴얼 보강은 한 묶음). 위험: 정한 기본값 둘은 소유자 확인 대상이다: 취약점 DB 받기 허용, 병합 커밋에 충돌 해결만. operate.md는 143/150줄, improve.md 144/150줄로 상한에 가깝다. 검증: check-work-docs(진입 경로 최대 269/350), check-docs, unittest 모두 rc=0.
2.7 KiB
2.7 KiB
용어
이 repo가 영어 그대로 쓰는 말과, 한국어로 정한 말의 뜻이다. 문서는 처음 나올 때 이 표기를 쓴다. 용어 순서(자연스러운 한국어 → 한국어(영어) → 영어 그대로)의 정본은 design-docs conventions/docs-system.md 3절이다.
| 표기 | 뜻 |
|---|---|
| leaf | registry(src/config/architecture/modules.json)에 등록된 Gradle 프로젝트 하나. 경계의 단위다 |
| family | 이름 앞부분이 같은 leaf 묶음(adapter:inbound:*, messaging:*). 공통 규칙은 그 폴더의 AGENTS.md다 |
| registry | leaf 목록·경로·허용 의존의 정본 파일 src/config/architecture/modules.json |
| capability | runtimeOnly 한 줄로 켜고 끄는 부가 기능 모듈(docs/manual/10-capabilities.md) |
| 조립(composition) | 기능을 엮기만 하는 leaf(src/composition/*)나 app-bootstrap의 배선 |
| lane | 같은 조건(실 DB, 컨테이너, 시간)으로 묶어 돌리는 테스트 실행 단위. strict lane은 build-logic strictTestLanes가 정의한 것 |
| 단계 | workflow가 게이트를 도는 때: PR, main, nightly, 태그 |
| 개발 환경 | 루트 compose.yaml 하나로 띄우는 로컬 스택(앱 컨테이너의 Spring 프로필은 local). src/app-bootstrap/compose-lanes/의 overlay는 테스트 lane fixture다. 그중 dev.yaml·prod-smoke.yaml은 앱을 Spring 프로필 dev·prod로 띄워 그 프로필의 기동을 보는 lane이고, 개발 환경이 아니다 |
| 게이트 | 통과해야 병합·릴리스하는 검사(docs/work/reference/gates.md) |
| outbox | 트랜잭션 안에 남긴 이벤트를 relay가 나중에 발행하는 방식 |
| HARD-STOP | 어기면 동작해도 완료가 아닌 일곱 조건(루트 AGENTS.md) |
| brief | 다른 세션에 일을 맡기는 지시문(docs/work/delegate.md) |
| 총괄 | 일을 나누고 brief를 쓰고 결과를 대조하는 세션 |
| 하위 세션 | 총괄이 띄운 별도 세션. 파일을 바꾸는 위임을 맡는다. 소유자가 열어 보고 멈출 수 있다 |
| 서브에이전트 | 한 세션 안에서 Agent 도구로 띄우는 도우미(.claude/agents/). 결과만 돌려준다 |
| 훅, 넛지 | 훅은 Claude Code가 정해진 때 대신 돌리는 명령(scripts/hooks/). 넛지는 막지 않고 알리기만 하는 훅이다 |
| 탐침 | 의심 결함을 보려고 버릴 worktree에서 잠깐 돌리는 테스트(docs/work/reference/gates.md 2절) |
| RED, GREEN | 수정 전 실패를 실행으로 본 것, 수정 뒤 통과를 본 것 |
| 살아 있는 문서, 기록 | 코드와 같이 고치는 문서, 쓴 때의 글로 두고 머리 블록만 고치는 문서(docs/README.md) |