refactor: 분리되어 관리하고 있던 문서 시스템을 하나로 통일
This commit is contained in:
DongHyeonka
@@ -0,0 +1,51 @@
|
||||
---
|
||||
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.
|
||||
@@ -0,0 +1,67 @@
|
||||
# Detailed Analysis Contract
|
||||
|
||||
## First pass: project map
|
||||
|
||||
Before interpreting architecture, establish:
|
||||
|
||||
- repository revision/snapshot;
|
||||
- build system and top-level build graph;
|
||||
- modules and their declared dependencies;
|
||||
- runtime applications/entry points;
|
||||
- persistence/messaging/cache/object storage/external service adapters;
|
||||
- test modules and test types;
|
||||
- configuration sources and environment boundaries.
|
||||
|
||||
The map is evidence, not a taxonomy exercise. Do not infer module responsibilities from names alone; inspect representative source and wiring.
|
||||
|
||||
## Bounded analysis
|
||||
|
||||
A bounded scope should be small enough that one run can answer all of these:
|
||||
|
||||
1. What public/consumed surface does the scope expose?
|
||||
2. What does it depend on and why?
|
||||
3. How is it wired into a running application?
|
||||
4. What state/data does it read or change?
|
||||
5. What are its main success and failure paths?
|
||||
6. What tests exercise it, and what do those tests actually prove?
|
||||
7. What behavior/configuration is declared but not actually connected?
|
||||
8. What operational or build-time constraints affect it?
|
||||
9. Which observations could become Case/Reference/Question/Decision material later?
|
||||
|
||||
## Code tracing
|
||||
|
||||
Prefer symbol/path-based traces over broad summaries. Record exact source anchors in `source-index.md` and analysis prose.
|
||||
|
||||
Where useful, trace:
|
||||
|
||||
- inbound request/event/command;
|
||||
- DTO/contract mapping;
|
||||
- application use case/port;
|
||||
- domain invariants/state transitions;
|
||||
- transaction boundary;
|
||||
- outbound port and adapter;
|
||||
- ORM/query behavior;
|
||||
- cache/messaging semantics;
|
||||
- error translation;
|
||||
- logs/metrics/tracing;
|
||||
- response/event side effect.
|
||||
|
||||
## Tests
|
||||
|
||||
Do not equate a green test suite with a verified architectural claim. For each important test, state what input is exercised, which real components are replaced, and what assertion proves. When a rule is enforced by build configuration or architecture tests, identify the failure point that would catch a violation.
|
||||
|
||||
## Git history
|
||||
|
||||
Use history when current code cannot explain why a boundary/decision exists or when a Case depends on an evolution sequence. A current code shape alone proves existence, not historical motivation.
|
||||
|
||||
## Final synthesis
|
||||
|
||||
`final/document.md` is not a shortened executive summary. It is the detailed project analysis assembled from bounded documents. Preserve:
|
||||
|
||||
- measured/observed behavior;
|
||||
- failed approaches when evidenced;
|
||||
- alternatives actually considered;
|
||||
- unresolved questions;
|
||||
- explicit decisions;
|
||||
- limitations of the analysis;
|
||||
- evidence/source references.
|
||||
@@ -0,0 +1,133 @@
|
||||
# Deep Analysis Standard
|
||||
|
||||
This is the completion standard for one bounded module/subsystem. A run may stop mid-scope, but it may not mark the scope complete until every gate below is satisfied.
|
||||
|
||||
## 1. Quantified scope map
|
||||
|
||||
Measure before interpreting. Record at least when applicable:
|
||||
|
||||
- module/leaf path and declared dependencies;
|
||||
- production file count and approximate LOC;
|
||||
- package/directory count and top-level children;
|
||||
- public interfaces/ports;
|
||||
- entities/tables/repositories;
|
||||
- migrations and independent migration streams;
|
||||
- unit/integration/contract/performance/architecture test counts;
|
||||
- runtime memberships/entry applications;
|
||||
- major feature flags/config namespaces.
|
||||
|
||||
Do not claim "fully read" without a countable denominator.
|
||||
|
||||
## 2. Coverage ledger
|
||||
|
||||
Create a ledger for the selected scope. Every materially relevant file or coherent file group receives one disposition:
|
||||
|
||||
- `FULL_READ` — contents read and incorporated into analysis;
|
||||
- `STRUCTURAL_ONLY` — structure/signature inspected because internals add no further information;
|
||||
- `EXCLUDED` — intentionally outside this document, with concrete dependency/ownership evidence explaining why.
|
||||
|
||||
Record counts by disposition. A scope cannot be `COMPLETE` while relevant files are `UNCLASSIFIED`.
|
||||
|
||||
## 3. Architecture reconstruction
|
||||
|
||||
Reconstruct from code rather than names:
|
||||
|
||||
- why the module exists and what it explicitly is not;
|
||||
- package/component ownership;
|
||||
- allowed and observed dependency edges;
|
||||
- source dependency versus runtime call flow;
|
||||
- composition-root wiring and conditional activation;
|
||||
- build/ArchUnit/registry gates and the exact failure point;
|
||||
- optional/experimental/stable boundaries.
|
||||
|
||||
If a design document says one thing and the current code says another, record the drift; do not silently reconcile it.
|
||||
|
||||
## 4. Contract and invariant extraction
|
||||
|
||||
For important types/functions/configuration, identify:
|
||||
|
||||
- constructor/type invariants;
|
||||
- bounds, allowlists, fail-closed behavior;
|
||||
- state machines and legal transitions;
|
||||
- transaction/retry/idempotency semantics;
|
||||
- concurrency and lifecycle assumptions;
|
||||
- security/privacy/redaction constraints;
|
||||
- database/provider-specific behavior.
|
||||
|
||||
Prefer the exact enforcing code path over a generic explanation.
|
||||
|
||||
## 5. Success and failure mechanics
|
||||
|
||||
For each major capability, cover both:
|
||||
|
||||
- normal execution path;
|
||||
- material failure paths and their translation/recovery behavior.
|
||||
|
||||
Look for silent failure modes: configuration that looks enabled but is not wired, green tests that replace the real failing component, unused beans/classes, fallback behavior that hides typos, provider differences, partial migration states, cache coherence assumptions, or retry paths that production never calls.
|
||||
|
||||
## 6. Tests as evidence
|
||||
|
||||
Inventory test lanes and explain what they prove. For important claims, identify:
|
||||
|
||||
- test class/path;
|
||||
- real versus replaced components;
|
||||
- input/fixture;
|
||||
- decisive assertion;
|
||||
- what remains unproved.
|
||||
|
||||
Run safe tests or focused probes when needed. Do not infer production behavior solely from test names.
|
||||
|
||||
## 7. History and rationale
|
||||
|
||||
Use comments/docs/Git history when needed to distinguish:
|
||||
|
||||
- current fact;
|
||||
- explicit historical rationale;
|
||||
- inferred rationale;
|
||||
- old behavior/bug;
|
||||
- fix and regression guard.
|
||||
|
||||
Preserve useful failure history. A bug fix is more valuable when the document explains why the bug was possible and what now prevents recurrence.
|
||||
|
||||
## 8. Static reachability and wiring checks
|
||||
|
||||
For major abstractions and registered components, check whether production code actually consumes them. Search injection sites, references, registration, conditional imports, and runtime membership. Record:
|
||||
|
||||
- active path;
|
||||
- duplicate path;
|
||||
- dead/unwired path;
|
||||
- configuration mismatch;
|
||||
- declared capability with insufficient evidence.
|
||||
|
||||
## 9. Runtime / database evidence
|
||||
|
||||
When safe and useful, verify claims with the real engine/runtime rather than an in-memory substitute. Preserve command/output in raw evidence and render terminal UI only from that captured output. State the environment and what the result does **not** generalize to.
|
||||
|
||||
## 10. Improvement backlog
|
||||
|
||||
End each completed bounded analysis with findings discovered while reading. Prioritize `P0/P1/P2/P3` (or justify another scheme). Each item should contain:
|
||||
|
||||
- fact/evidence;
|
||||
- why it matters;
|
||||
- exact verification command/test;
|
||||
- candidate options when supported;
|
||||
- whether it belongs to Case, Reference, Open Question, or Decision later.
|
||||
|
||||
Do not invent a defect merely to fill this section. An empty backlog is allowed if the evidence supports it.
|
||||
|
||||
## 11. Completion gate
|
||||
|
||||
A bounded scope is complete only when:
|
||||
|
||||
- quantified scope denominator exists;
|
||||
- coverage ledger has no unclassified relevant items;
|
||||
- top-level package/component map is accounted for;
|
||||
- build/runtime wiring is traced;
|
||||
- important invariants and failure paths are documented;
|
||||
- tests and evidence are mapped to claims;
|
||||
- explicit rationale is separated from inference;
|
||||
- dead/unwired/duplicate paths were checked;
|
||||
- limitations and excluded areas are stated;
|
||||
- improvement backlog was considered.
|
||||
|
||||
If this cannot fit reliably in one run, keep the scope `IN_PROGRESS` and continue it on the next scheduled run. Never lower the depth standard to finish on schedule.
|
||||
@@ -0,0 +1,39 @@
|
||||
# Evidence Contract
|
||||
|
||||
## Primary evidence first
|
||||
|
||||
Store command output, logs, generated query plans, benchmark results, browser observations, and other primary material under `docs/<프로젝트>/evidence/raw/` before creating presentation assets.
|
||||
|
||||
## Terminal evidence
|
||||
|
||||
For a command used as evidence, retain:
|
||||
|
||||
- exact command (without embedded credentials);
|
||||
- working directory;
|
||||
- executed timestamp;
|
||||
- exit code;
|
||||
- raw stdout/stderr;
|
||||
- source revision when relevant.
|
||||
|
||||
Render terminal UI with `./tools/terminal-evidence/render_terminal.py`.
|
||||
|
||||
The visual asset is explanatory. The raw evidence is the provenance.
|
||||
|
||||
## Browser evidence
|
||||
|
||||
A screenshot record should state:
|
||||
|
||||
- URL/origin;
|
||||
- code revision/environment;
|
||||
- setup state;
|
||||
- action performed;
|
||||
- what visible/network fact the screenshot demonstrates;
|
||||
- what it does not demonstrate.
|
||||
|
||||
## Diagram evidence
|
||||
|
||||
Architecture/sequence/state SVGs are derived explanations. Their nodes/edges must be traceable to code/config/runtime evidence. Do not draw a desired architecture and present it as the current architecture.
|
||||
|
||||
## Measurements
|
||||
|
||||
Every metric needs a context: dataset/workload, environment, relevant configuration, measurement method, and comparison condition. Preserve raw measurement results where practical.
|
||||
@@ -0,0 +1,87 @@
|
||||
# Analysis Queue Contract
|
||||
|
||||
`<분석 대상 저장소>/analysis-queue.yaml` is the first control file read by every detailed-analysis run. It is the SSOT for project order, active-project ownership, and explicit reanalysis requests.
|
||||
|
||||
## State model
|
||||
|
||||
Allowed project states:
|
||||
|
||||
- `PENDING` — queued, never started for the current analysis history;
|
||||
- `IN_PROGRESS` — the project currently owned by the 09:00 analysis run;
|
||||
- `COMPLETE` — all intended scopes and `final/document.md` are complete for the recorded source snapshot;
|
||||
- `REANALYZE` — a previously completed project explicitly queued for another analysis cycle after source changes or a requested re-review;
|
||||
- `BLOCKED` — the active project cannot continue because required source, instructions, or environment are unavailable;
|
||||
- `SKIPPED` — explicitly excluded by the user or queue owner.
|
||||
|
||||
At most one project may be `IN_PROGRESS`. `activeProject` must be `null`, or name the project currently owned by the analysis worker. An owned project may be `IN_PROGRESS` or `BLOCKED`. A `REANALYZE` entry is queued, not active, until a scheduled run activates it.
|
||||
|
||||
## Mandatory run order
|
||||
|
||||
1. **Read `analysis-queue.yaml` before scanning project contents.**
|
||||
2. Discover direct project directories under `<분석 대상 저장소>`. Ignore control files and hidden infrastructure directories.
|
||||
3. Append newly discovered, unlisted projects to the **end** of `projects` as `PENDING`. Never insert them ahead of existing entries automatically.
|
||||
4. If `activeProject` names an `IN_PROGRESS` project, continue only that project.
|
||||
5. If `activeProject` names a `BLOCKED` project, do not start another project. Re-check only the blocking prerequisite; resume as `IN_PROGRESS` when resolved, otherwise leave it blocked and stop.
|
||||
6. If there is no active project, scan queue entries from top to bottom and choose the first actionable entry whose state is `PENDING` or `REANALYZE`.
|
||||
7. For `PENDING`, set it to `IN_PROGRESS`, set `activeProject`, initialize/continue `docs/<프로젝트>/state.json`, and run the normal exhaustive analysis cycle.
|
||||
8. For `REANALYZE`, execute the reanalysis activation procedure below, then set it to `IN_PROGRESS` and set `activeProject`.
|
||||
9. Continue the active project across scheduled runs until its required scopes are complete and `final/document.md` is synthesized for the target source snapshot.
|
||||
10. Only then mark the entry `COMPLETE`, update the completed source revision, clear `activeProject`, and allow a later scheduled run to select the next actionable entry.
|
||||
|
||||
Do not begin another project in the same run after completing one. Completion creates a clean scheduling boundary.
|
||||
|
||||
## Reanalysis activation
|
||||
|
||||
`REANALYZE` is an explicit user request to analyze a project again **without deleting the previous detailed analysis**.
|
||||
|
||||
Before changing `REANALYZE` to `IN_PROGRESS`:
|
||||
|
||||
1. Read the existing `docs/<프로젝트>/state.json` and `final/document.md`.
|
||||
2. Resolve the previous completed source snapshot. Prefer `finalDocument.sourceRevision`; fall back only to another explicitly recorded completed revision. If no trustworthy baseline exists, mark the project `BLOCKED` with a note rather than pretending this is incremental reanalysis.
|
||||
3. Resolve the current target source revision. For Git repositories, record `git rev-parse HEAD` and working-tree status. Do not modify/reset source.
|
||||
4. Compare baseline → target before reopening scopes. Record changed paths and the evidence used to map those paths to bounded scopes.
|
||||
5. Set `reanalysis.baselineRevision`, `reanalysis.targetRevision`, `reanalysis.changedPaths`, `reanalysis.impactedScopes`, increment `analysisCycle`, and set `reanalysis.requestedAt`.
|
||||
6. Choose a reanalysis mode:
|
||||
- `IMPACTED_SCOPES` when changed paths can be mapped confidently to bounded scopes and project/module boundaries remain stable;
|
||||
- `FULL_PROJECT` when module/build boundaries, shared contracts, architecture rules, cross-cutting configuration, migration ownership, generated sources, or scope mapping itself changed, or when impact cannot be bounded confidently.
|
||||
7. Reopen only the impacted scopes for `IMPACTED_SCOPES`, but keep previous analysis as historical baseline. Rebuild the project-wide synthesis after those scopes complete.
|
||||
8. For `FULL_PROJECT`, re-establish the project inventory and coverage ledger from the target snapshot and revalidate every intended scope.
|
||||
|
||||
A reanalysis cycle must never silently overwrite the fact that earlier documents described an earlier source snapshot. Preserve revision provenance in state and analysis prose where it matters.
|
||||
|
||||
## Reanalysis completion
|
||||
|
||||
When reanalysis finishes:
|
||||
|
||||
- update every reopened scope to complete for the target revision;
|
||||
- synthesize `final/document.md` again, including material changes from the prior snapshot when relevant;
|
||||
- set `finalDocument.sourceRevision` to the target revision;
|
||||
- set `reanalysis.completedAt`;
|
||||
- mark the queue entry `COMPLETE`;
|
||||
- clear `activeProject`.
|
||||
|
||||
The 10:00 root-tree stage will see the changed final document and may then update decomposition/readiness. The 11:00 generation stage remains grounded in that updated tree.
|
||||
|
||||
## New projects and ordering
|
||||
|
||||
A new directory may appear while another project is being analyzed. Append it as `PENDING`; **do not preempt the active project**. `REANALYZE` also does not preempt the active project. The user may reorder queued `PENDING` and `REANALYZE` entries manually. Automatic runs never reorder existing entries.
|
||||
|
||||
## Blocked projects
|
||||
|
||||
If the active project disappears, cannot be read, lacks a trustworthy reanalysis baseline, or requires an unavailable prerequisite, mark it `BLOCKED`, retain it as `activeProject`, record the reason, and stop. Do not silently jump to the next project. Resuming means returning the same entry to `IN_PROGRESS`; skipping requires explicit `SKIPPED` and clearing `activeProject`.
|
||||
|
||||
## Example: explicit reanalysis request
|
||||
|
||||
```yaml
|
||||
version: 1
|
||||
activeProject: null
|
||||
projects:
|
||||
- name: backend-clean-architecture
|
||||
status: REANALYZE
|
||||
- name: tech-log-backend
|
||||
status: PENDING
|
||||
- name: ca-tmpl
|
||||
status: PENDING
|
||||
```
|
||||
|
||||
On the next run, if the first project has a trustworthy completed baseline, it becomes the active `IN_PROGRESS` project and begins a new analysis cycle.
|
||||
Reference in New Issue
Block a user