4.1 KiB
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, applyreferences/queue-contract.md: reconcile newly discovered project directories, preserve queue order, and determine the single active project. - If an
IN_PROGRESSproject exists, analyze only that project. If none exists, activate the firstPENDINGproject in queue order. Never preempt an active project because a new project appeared. - For the selected
<분석 대상 저장소>, check the nearestAGENTS.mdor equivalent repository instructions. - Record Git revision and
git statuswhen Git is available. Never modify or reset user source as part of analysis. - Read
docs/<프로젝트>/state.jsonif it exists; otherwise initialize fromdocs/_templates. - 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, andstate.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. Then synthesize
final/document.mdwithout dropping provenance or limitations, mark its queue entryCOMPLETE, and clearactiveProject. Do not start the next project before this completion transition.
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.