Files

T

DongHyeonkaandClaude Fable 5.1 9d2a3725c5 pipeline: make tech-log-tree.json the one decomposition contract and enforce it

리뷰 두 건을 반영했다.

계약
- tech-log-tree.json 하나가 분해 계약이자 색인이다. 사람이 읽는 트리·Node Specification·
후보 대장은 없어졌고, 문서에 남아 있던 그 개념을 걷어냈다
- candidateScope — 후보를 찾는 SSOT 범위. 접어 넣은 제2부·제3부는 근거이지 후보가 아니다
- sourceRepository — 분석한 저장소의 경로·리비전·판단 근거. 리비전을 모르면 null 로 두고
지어내지 않는다. 갈래가 여럿이면 revisions
- 검사기: 계약 미채택·PENDING·PROMOTE↔글감 양방향·candidateScope·sourceRepository 를
error/warn 으로 센다. 옛 스키마도 검사를 피하지 못한다. 테스트 22 → 31

기록 쓰기
- 템플릿 5종에 source·sourceRevision·topicName, Question 에 닫는 조건, 본문 없는 종류에서
assets 제거. 고정 절 개수 삭제
- check_evidence.mjs — 인용한 코드가 SSOT 에 있는지, 앵커가 SSOT 를 가리키는지, 제목이
계약과 같은지, 리비전이 저장소에 있는지. 게시된 기록에서 SSOT 와 다른 URL 을 잡았다

문체
- 문체 규칙의 정본을 ai-tells.md 로. explaining.md 의 질문체 제목·절 끝 대조 반복·그림 예고
규칙을 삭제해 충돌을 없앴다. 첫 절 「설명 뒤에 평가를 붙이지 않는다」에 지우는 사례 네 유형
- voice 스킬의 「독자 쪽을 본다」를 자료에 오독 기록이 있을 때로 좁히고, 평가만 더한 예시를 교체
- check_prose: 안내 문장을 요구하던 경고 제거, 문장이 끝나지 않은 채 문단이 끝나는 조각 검사 추가

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

2026-09-07 12:39:20 +09:00

5.4 KiB

Raw Blame History

name, description

name	description
analyzing-codebase-for-tech-log	Use when a project under <분석 대상 저장소> must be deeply analyzed and documented under docs, especially when the repository is too large for one pass and analysis must proceed by bounded module or subsystem.

Analyzing Codebase For Tech Log

Goal

Produce a highly detailed, source-traceable engineering analysis. This stage discovers facts and evidence; it does not write Tech Log records yet.

Required sequence

First read <분석 대상 저장소>/analysis-queue.yaml. Before inspecting any project contents, apply references/queue-contract.md: reconcile newly discovered project directories, preserve queue order, and determine the single active project.
If an IN_PROGRESS project exists, analyze only that project. If none exists, activate the first PENDING project in queue order. Never preempt an active project because a new project appeared.
For the selected <분석 대상 저장소>, check the nearest AGENTS.md or equivalent repository instructions.
Record Git revision and git status when Git is available. Never modify or reset user source as part of analysis.
Read docs/<프로젝트>/state.json if it exists; otherwise initialize the working material from templates/ in this skill. The project folder template (docs/_templates/) holds only the finished shape and does not carry it.
Map repository/build/module boundaries before choosing a scope.
If the repository is large, select one bounded unanalysed module/subsystem and analyze it completely. Do not skim the whole repository and call that detailed analysis.
Update source-index.md, the bounded analysis file, coverage ledger, evidence, and state.json.
Capture runtime evidence only where it resolves a material uncertainty or verifies a significant claim.
Continue the same project across runs until all intended scopes are complete.
Fold the analysis into final/document.md. Not a summary of it — the material itself, with provenance and limitations intact. The test is that every claim a Tech Log record will cite can be anchored in final/document.md alone. Anything that survives only in analysis/** has not been folded in.
Remove the working material. analysis/, notes/, checkpoints/, state.json, and source-index.md exist only while the analysis runs. A finished project folder holds final/ and tech-log-studio/ (and source/ when the material came from outside). Then mark the queue entry COMPLETE and clear activeProject. Do not start the next project before this completion transition.

python3 scripts/fold-analysis-into-final.py <project> performs steps 11 and 12: it moves the module analyses into part 2 of final/document.md, the source index, scope coverage and process notes into part 3, rewrites every analysis/NN anchor to final/document.md#aNN, and removes the working material.

analysisStatus: COMPLETE while the working material is still on disk means step 11 was skipped — the analysis was summarized rather than folded in, and downstream records will anchor on analysis/** instead of the SSOT. scripts/verify-project-layout.py and scripts/verify-tech-log-tree.py count that state.

Read references/queue-contract.md, references/analysis-contract.md, references/deep-analysis-standard.md, and references/evidence-contract.md before analysis.

Evidence vocabulary

Label statements internally as:

observed: directly seen in code/config/test/runtime/git evidence;
inferred: conclusion logically derived from observed sources;
hypothesis: plausible explanation not yet verified;
unknown: material information not available;
external: knowledge from outside the codebase, clearly separated from project observation.

Do not turn inference into observation in the final document.

Depth rule

A selected bounded scope is an exhaustive-reading unit, not a representative-sampling unit. Build an inventory first, then account for every production source/config/build/migration/test file that materially belongs to that scope. Each item must be marked FULL_READ, STRUCTURAL_ONLY, or EXCLUDED with a reason. EXCLUDED is allowed only when dependency/import/ownership evidence shows it does not contribute to the scope being documented.

For the selected scope, trace representative behavior end-to-end where applicable: entry point → application policy → domain/state → persistence/external adapter → observable result. Also trace failure paths, transactions, concurrency, lifecycle, configuration, tests, build-time enforcement, runtime wiring, dead/unwired paths, and historical bug/decision evidence when they materially affect the architecture.

Do not stop at "what classes exist". Explain why the shape exists only when code comments, tests, design docs, Git history, runtime evidence, or a clearly labeled inference supports the explanation.

There is no target document length. A 3,000+ line module analysis is acceptable when the source warrants it; artificial verbosity is not. Completeness is judged by the coverage ledger and source traceability, not by prose length.

Stop conditions

Do not run destructive/state-changing commands merely to create evidence. Do not expose secrets. If a runtime check would alter production or shared external state, leave it as an evidence task instead.

5.4 KiB Raw Blame History