52 lines
4.1 KiB
Markdown
52 lines
4.1 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 from `docs/_templates`.
|
|
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. Then synthesize `final/document.md` without dropping provenance or limitations, mark its queue entry `COMPLETE`, and clear `activeProject`. 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.
|