DongHyeonkaandClaude Fable 5.1
9d2a3725c5
리뷰 두 건을 반영했다. 계약 - 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>
71 lines
5.4 KiB
Markdown
71 lines
5.4 KiB
Markdown
---
|
|
name: analyzing-codebase-for-tech-log
|
|
description: 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
|
|
|
|
1. **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.
|
|
2. 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.
|
|
3. For the selected `<분석 대상 저장소>`, check the nearest `AGENTS.md` or equivalent repository instructions.
|
|
4. Record Git revision and `git status` when Git is available. Never modify or reset user source as part of analysis.
|
|
5. 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.
|
|
6. Map repository/build/module boundaries before choosing a scope.
|
|
7. 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.
|
|
8. Update `source-index.md`, the bounded analysis file, coverage ledger, evidence, and `state.json`.
|
|
9. Capture runtime evidence only where it resolves a material uncertainty or verifies a significant claim.
|
|
10. Continue the same project across runs until all intended scopes are complete.
|
|
11. **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.
|
|
12. **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.
|