실습 스캐폴드 계획 — 예제마다 경로·패키지·실행명령¶
목적: java-study 챕터의 코드 예제를 "읽는 자료"에서 "따라 하는 자료"로 만든다. 사용자 피드백(2026-07-03): "실제로 해보니 클래스명을 어떻게 지을지부터 고민하더라. 어느 프로젝트의 어느 경로에 어떤 파일을 만들지, 패키지 구분, 실행 명령까지 딱 제공해야 실습하기 좋다."
진단 근거: 2026-07-03 에이전트 2병렬 조사 (ch01~05 / ch06~11).
1. 진단 요약¶
완결 실습 예제 약 76개(Core 58 + Spring·고급 18) 중 경로·패키지·실행명령 3요소를 모두 갖춘 것은 3~4개(ch05 소켓·JDBC)뿐.
| 파일 | 완결 예제 | 경로 | package | 실행명령 | 핵심 문제 |
|---|---|---|---|---|---|
| ch01 | 2 | 부분 | 0 | 부분 | 1.2에서 만든 프로젝트와 코드블록 미연결 |
| ch02 | 20 | 0 | 0 | 0 | 드라이버 19개 전부 Main(충돌), 한 블록에 public 클래스 여러 개(그대로 컴파일 불가) |
| ch03 | 0 | — | — | — | 전부 스니펫 (main 없는 조각·노트북 스타일 top-level 문장) |
| ch04 | 8 | 0 | 0 | 0 | 패턴 After 8개 전부 무스캐폴드, Before/After 클래스명 중복 |
| ch05 | 28 | ~8 | 4 | ~6 | 스캐폴드 시도 최다이나 따라 하면 컴파일 실패 버그(파일명↔클래스명 불일치, package 유무 불일치) + 5.9-1 외부 라이브러리 의존성 안내 없음 |
| ch06 | 0 | — | — | — | 6.1 신규 demo ↔ 뒷부분 day_by_spring 프로젝트 가정 불일치 |
| ch07 | ~7 | 0 | 0 | 0 | 실습 저장소가 Querydsl 미도입이라 넣을 곳 자체가 불명 + LoanRepository 이중 정의 |
| ch08 | 0 | — | — | — | 전부 발췌 (curl 왕복 실습은 우수, day_by_spring 전제) |
| ch09 | 3 | 2 | 0 | 3 | 경로는 있는데 package 선언 누락 → 그대로 넣으면 컴파일 에러 |
| ch10 | 0 | — | — | — | 전부 개념 데모 |
| ch11 | ~8 | ~6 | ~7 | 1~2 | §11.23 블로그가 모범(트리+경로+package 일치), 실행 명령만 없음 |
2. 확정 정책 (2026-07-03 사용자 결정)¶
- Spring 실습 = 자족형(self-contained) — ch06 6.1에서 start.spring.io로 만드는
demo프로젝트를 Spring 챕터의 공식 실습 프로젝트로 승격.day_by_spring은 "참고: 실제 프로젝트에서는" 격으로만 언급(private 저장소라 학습자 접근 불가). 저장소 공개는 보류(2026-07-03 사용자 결정) — "막혔을 때 문서만으로 충분히 참고되도록" 각 실습 절 끝에 "자주 나는 에러 → 원인" 부기를 두는 것으로 대체(§7-7 자족성 규칙). 시크릿 스캔은 완료 상태(실유출 0건,.env.example의 Supabase 호스트만 플레이스홀더 교체 필요)라 나중에 공개하려면 커밋 1개+URL 한 줄이면 됨. - ch07 Querydsl 실습 가능화 — 의존성·Q타입 생성·엔티티까지 갖춘 "Querydsl 실습 환경 만들기" 절을 신설하고 완결 클래스 7개에 스캐폴드 부착.
LoanRepository이중 정의 통합. - ch03 전면 실행형화 — 절마다 스니펫들을 주제별 Demo 클래스로 묶어 실행 가능하게 재구성(기존 "예상 결과"와 정합). 비교용 2~3줄 발췌는 스니펫으로 유지.
- Core(ch01~05) 실습 = ch01 1.2 프로젝트 승계 — 챕터별 패키지
com.example.chNN.
3. §7-7 실습 스캐폴드 표준 (authoring-standards에 넣을 내용)¶
구분: 모든 코드블록은 스니펫(발췌·비교·퀴즈 — 스캐폴드 불필요) 또는 실습 예제(파일로 만들어 실행하는 단위 — 4요소 필수) 둘 중 하나. 완결 클래스 외형인데 실습용이 아니면 "참고 코드" 라벨로 구분.
실습 예제 4요소:
- 파일 리드인 — 코드블록 바로 위:
**파일**: src/main/java/com/example/ch02/AnimalDemo.java - package 선언 — 코드 첫 줄, 리드인 경로와 일치
- 한 블록 = 한 파일 — 파일명 = public 클래스명. 보조 클래스는 non-public으로 같은 파일 허용, public 여러 개면 블록 분리
- 실행 명령 + 예상 결과 — 예제(묶음) 끝에 bash 실행 명령 +
예상 결과펜스
챕터 → 프로젝트 매핑:
| 챕터 | 기준 프로젝트 | 패키지 |
|---|---|---|
| ch01~05, ch09 §9.2 | ch01 1.2에서 만든 Maven/Gradle 프로젝트 | com.example.chNN |
| ch05 소켓·JDBC | 단일 파일 javac 병행 허용 (작업 디렉터리 명시) | default 허용 |
| ch06~08·10 (Spring) | ch06 6.1 start.spring.io demo (자족형) |
com.example.demo.* |
| ch11 미니프로젝트 | 예제별 자체 프로젝트 (트리 제시, §11.23 모델) | 예제 자체 규칙 |
클래스명 규칙: 챕터 내 고유. 드라이버 클래스 Main 금지 → <주제>Demo. 실행 명령 표준형: 프로젝트는 Maven 우선(./mvnw compile exec:java -Dexec.mainClass=... 또는 테스트는 ./mvnw test -Dtest=...) + Gradle 대안, 단일 파일은 javac/java.
4. 실행 구조¶
Phase A 정책 확정 (완료 — §2)
Phase B §7-7 명문화 + scripts/scaffold-lint.sh 신작 + 캘리브레이션 ← 프롬프트 A
Phase C 챕터별 배치 적용 (3병렬 × 3배치 + 대형 단독) ← 프롬프트 B
배치1: ch02 · ch04 · ch09 (스캐폴드 부착 중심)
배치2: ch01 · ch06 · ch11 (프로젝트 연결·실행 명령 보강)
배치3: ch05 (버그 수정+대량 부착) · ch03 (전면 실행형화) · ch07 (실습 환경 신설) ← 대형, 사이클 5회
ch08·ch10: 프로젝트 전제 문구 정리만 (day_by_spring → 자족형/참고 격하)
Phase D 컴파일 스모크 검증 + 적대적 검수 + 배포 ← 프롬프트 C·D
종료 조건 3종: goal(scaffold-lint 0건 + 스모크 통과) / resource(파일당 3~5사이클) / budget(동시 3파일).
5. 업무지시 프롬프트¶
프롬프트 A — 시스템 구축 (1회)¶
§7-7 실습 스캐폴드 표준을 명문화하고 검증 게이트를 만든다.
1) wiki/guide-wiki-authoring-standards.md에 "### 7-7. 실습 스캐폴드 (코드 예제)" 신설 —
내용은 wiki/plan-practice-scaffold.md §3을 그대로 옮긴다 (구분 원칙·4요소·프로젝트
매핑 표·클래스명 규칙·실행 명령 표준형).
2) scripts/scaffold-lint.sh 작성 — 인자로 받은 파일에서 기계 검출 가능한 위반만 검사,
위반 시 exit 1 + 목록 출력:
① `**파일**:` 리드인의 경로에서 (패키지 경로, 파일명)을 추출해 바로 다음 java 펜스의
package 선언·public 클래스명과 대조 (불일치=위반)
② java 펜스 안에 public 최상위 타입(class/interface/enum/record)이 2개 이상이면 위반
③ 드라이버 검출: `public static void main`이 있는 클래스명이 `Main`이면 위반
④ 리드인 없는 완결 예제 검출은 휴리스틱 한계로 제외 (사람/검수 에이전트 몫)
3) 캘리브레이션: 모범(ch11 §11.23 블로그 구간)에 돌려 오탐 확인, 기지 위반(ch02 Main 19회,
ch05 L1830 파일명 불일치)에 돌려 검출 확인. 오탐 나면 스크립트 수정 후 재검증.
4) CLAUDE.md 셀프 체크에 "실습 예제 있는 페이지: scaffold-lint 통과" 1줄 추가.
완료 기준: §7-7 존재 + 캘리브레이션 통과 + build-site.sh 통과. 커밋 1개.
프롬프트 B — 챕터 정합 루프 (챕터당 1회)¶
대상: wiki/java-study-ch{NN}.md 를 §7-7 실습 스캐폴드 표준(guide-wiki-authoring-standards)에
정합시킨다. §7-7과 wiki/plan-practice-scaffold.md §2·§3을 먼저 읽어라.
루프 (기본 3사이클, 대형 챕터는 5사이클):
1. bash scripts/scaffold-lint.sh <파일> + 본문 정독으로 실습 예제/스니펫 구분
2. 수정:
- 실습 예제마다 4요소 부착 (파일 리드인·package·한 블록=한 파일·실행 명령+예상 결과)
- 드라이버 클래스 Main → <주제>Demo 개명 (본문 언급·예상 결과도 동기화)
- 챕터 내 클래스명 충돌 해소 (패키지 분리 또는 개명)
- 스니펫은 그대로 두되, 완결 클래스 외형인데 읽기용이면 "참고 코드" 라벨
유지 영역: 기존 코드 로직(스캐폴드 외 코드 내용 변경 금지 — package 추가·개명은 허용),
예상 결과 펜스 내부(출력이 바뀌는 개명만 동기화), 표, frontmatter(updated만)
3. scaffold-lint + style-lint + build-site.sh 통과 확인, git diff에서 로직 변경 없는지 확인
4. 통과 → 커밋(feat: chNN 실습 스캐폴드) 후 종료. 초과 → 남은 문제 보고 후 중단.
챕터별 추가 지시:
- ch01: 1.2에서 만든 프로젝트에 Hello 예제를 넣는 흐름으로 연결 (com.example.ch01)
- ch02: 반쪽 예제 4개(main 없이 예상 결과만)는 Demo 클래스로 승격
- ch03: 전면 실행형화 — 절마다 스니펫을 주제별 Demo로 묶어 main에서 순서 실행,
기존 "예상 결과"와 출력 정합. 비교용 짧은 발췌는 스니펫 유지
- ch04: 패턴별 After를 실습 예제로 (Before는 "참고 코드" 라벨), top-level 사용 예문은
Demo main으로 흡수. Before/After 클래스명 충돌은 패키지 분리(ch04.strategy 등)
- ch05: 기지 버그 수정 — L1830 파일명 Main.java↔FileIOHandlerMain 불일치,
Person(default)↔FileIOHandler(com.example.ch4.files) 패키지 불일치. 5.9-1 예제들엔
POI·Gson 의존성 좌표를 예제 옆에 명시. 패키지는 com.example.ch05로 통일
- ch06: 6.1 demo를 공식 실습 프로젝트로 승격 — 프로파일 절(6.x)을 "demo에
application-h2.yml 등을 직접 만들며 실행"하는 흐름으로 정리, day_by_spring 언급은
"참고: 실제 프로젝트에서는"으로 격하
- ch07: "Querydsl 실습 환경 만들기" 절 신설(demo에 의존성+Q타입 생성+Member/Team/Loan
엔티티) → 완결 클래스 7개에 스캐폴드 → LoanRepository 이중 정의 통합,
MemberListItem 필드 수 불일치 정정. 체인 발췌 ~30개는 스니펫 유지
- ch08·ch10: 실습 예제 0 — day_by_spring 전제 문구만 자족형 기준으로 정리
- ch09: 9.2 세 클래스에 package com.example.ch09 부착 + ExpressionParser 경로 안내 누락
보완. 9.1 스텁은 "참고 코드" 라벨
- ch11: §11.23 블로그에 실행 명령(war 빌드·Tomcat 배포) 보강, MemoApp에 경로·실행 추가
build-site.sh·커밋은 오케스트레이터 지시에 따를 것 (병렬 실행 시 금지).
프롬프트 C — 컴파일 스모크 검증 (Phase C 후 1회)¶
검증자 역할. scratchpad에 실제 Maven 프로젝트를 만들고, ch02·ch03·ch04·ch05·ch09에서
스캐폴드가 부착된 실습 예제를 챕터당 3개씩 골라 문서 그대로(경로·package·파일명) 생성한 뒤
문서의 실행 명령을 그대로 실행하라. 컴파일 실패·출력 불일치·경로 오류를 파일:라인과 함께
보고하라. 문서를 수정하지 말고 보고만. (Spring 챕터는 start.spring.io 생성까지가 무거우면
ch06 6.1 생성 명령 + ch07 Q타입 생성 명령의 문법 검증까지만.)
프롬프트 D — 적대적 검수 (전체 완료 후 1회)¶
검수자 역할. ch01~ch11을 읽고 §7-7 위반이 남았는지 적대적으로 찾아라: 4요소 빠진 실습
예제, 리드인↔package↔클래스명 불일치, 챕터 내 클래스명 충돌, "참고 코드" 라벨 없는
읽기용 완결 클래스, 실행 명령 없는 예제. 수정하지 말고 파일:라인+인용+PASS/REJECT만.
불확실하면 REJECT. REJECT는 프롬프트 B 재실행.
6. 진행 체크리스트¶
- Phase B — 프롬프트 A (§7-7 명문화 + scaffold-lint.sh + 캘리브레이션) — 2026-07-03 완료. 캘리브레이션: ch02
public class Main18건·ch05 파일명/package 불일치 3건 정확 검출, ch06·ch09 오탐 0. ch01 L187·ch11 L3185의 Main 검출은 Phase C 수정 대상(오탐 아님) - Phase C 배치 1 — ch02(예제 23개, Main 18 개명, 충돌 해소) / ch04(8패턴 실습화, Spring 3패턴은 demo 배치) / ch09(package 누락 보완) — 2026-07-03 완료
- Phase C 배치 2 — ch01(Hello 단일 파일 실습화+이관 다리) / ch06(demo 승격, yml 리드인 7개, day_by_spring 격하 5건) / ch11(§11.23 빌드·실행 신설, MemoApp 정합, 퀴즈 Main 강등) — 2026-07-03 완료
- Phase C 배치 3 (대형) — ch05(버그 수정+리드인 30개+의존성 블록) / ch03(전면 실행형화 — Demo 10개, 예상 결과 실측) / ch07(7.4-1 실습 환경 신설, 스캐폴드 14파일, LoanRepository 통합) — 2026-07-03 완료
- Phase C 마무리 — ch08·ch10 전제 문구 정리(demo 기준+참고 격하, ReachabilityExample 승격) — 2026-07-03 완료
- Phase D — 2026-07-03 완료:
- 컴파일 스모크: 20체크 중 17 PASS, 예제 코드 자체는 문자 단위 일치. 치명 발견 2건 — ch01 archetype pom 1.7 고정(Java 21 컴파일 불가), ch07 Q타입 미생성(Boot 4.x Lombok annotationProcessorPaths가 프로세서 자동 발견 차단) + ch09 mvnw 오용, ch05 샘플 데이터 부재
- 적대적 검수: ch05 실행명령·예상결과 대량 누락(lint 사각지대), 참고 코드 라벨 누락 8곳, ch11 MemoryMonitor 리드인 누락 등
- 수정 라운드(3병렬): 전부 반영. ch05는 25개 예제 전량 실측(실측 중 실코드 버그 2건 — BufferedReader 재사용·Jackson getter — 추가 발견·수정). scaffold-lint에 규칙 ④(절 단위 실행 명령·예상 결과 검사) 보강
- 마감 — 11개 챕터 전체 scaffold-lint·style-lint 위반 0건, backlog·log 기록, §7-7 셀프체크 편입, 배포 — 2026-07-03
관련 페이지¶
- plan-tone-consistency — 같은 방법론(표준 명문화→무료 게이트→배치 루프→검수)의 선행 사례
- guide-wiki-authoring-standards — §7-7이 들어갈 곳
- java-study-ch01 — Core 실습 프로젝트의 출발점 (1.2)
- backlog — 진행 상태 인계