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.
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
name: deriving-tech-log-root-tree
|
||||
description: Use when a completed or substantially completed docs project analysis must be decomposed into grounded Tech Log Topics and candidate Case, Reference, Open Question, and Decision records.
|
||||
---
|
||||
|
||||
# Deriving Tech Log Root Tree
|
||||
|
||||
## Core rule
|
||||
|
||||
**Discover record candidates from evidence already present in the detailed analysis. Do not brainstorm a content calendar.**
|
||||
|
||||
## Required sequence
|
||||
|
||||
1. Read project `state.json`, `final/document.md`, and `source-index.md`.
|
||||
2. Read bounded analysis files when the final document's anchor is not enough to judge classification.
|
||||
3. Identify coherent Topics from shared engineering problem spaces, not merely folder/module names.
|
||||
4. Within each Topic, identify concrete incidents first (Case), then reusable rules (Reference), unresolved unknowns (Open Question), and explicit project choices (Decision).
|
||||
5. Write the human-readable PROJECT/TOPIC tree.
|
||||
6. Add a Node Specification for every title with source anchors, readiness, relations, and kind-specific metadata.
|
||||
7. Run `references/decomposition-checklist.md`.
|
||||
8. Hash the source detailed document and record the project revision so downstream generation can detect staleness.
|
||||
|
||||
Use `.agents/skills/writing-tech-log-records/references/root-tree-contract.md` as the output contract.
|
||||
|
||||
## Topic boundary
|
||||
|
||||
A Topic is a stable problem/decision area whose records share terminology, evidence, and relations. It should be broad enough to connect several records when the evidence supports them, but narrow enough that its References and Decisions remain coherent.
|
||||
|
||||
Do not create one Topic per source file. Do not force unrelated incidents into one Topic because they use the same framework.
|
||||
|
||||
## Classification discipline
|
||||
|
||||
- Case title names the concrete engineering problem/verification, not a generic technology lesson.
|
||||
- Reference title names a reusable criterion/distinction.
|
||||
- Open Question title states an uncertainty that is still unresolved.
|
||||
- Decision title states an actual/proposed project direction evidenced in sources.
|
||||
|
||||
Branches may be empty. Symmetry is not a quality goal.
|
||||
@@ -0,0 +1,43 @@
|
||||
# Root Tree Decomposition Checklist
|
||||
|
||||
## Source integrity
|
||||
|
||||
- [ ] The tree records the detailed document hash and project revision/snapshot.
|
||||
- [ ] Every node has at least one source anchor.
|
||||
- [ ] Source anchors actually contain the material implied by the title.
|
||||
- [ ] Runtime-dependent claims name evidence or use `NEEDS_EVIDENCE`.
|
||||
|
||||
## Topic quality
|
||||
|
||||
- [ ] Topic is a coherent engineering problem space rather than a directory name.
|
||||
- [ ] Two Topics do not merely split the same causal chain arbitrarily.
|
||||
- [ ] A large Topic is split when its records no longer share useful relations/criteria.
|
||||
|
||||
## Case
|
||||
|
||||
- [ ] There is a specific incident, experiment, failure, diagnosis, or verification sequence.
|
||||
- [ ] The title can be understood without inventing a historical story.
|
||||
- [ ] The conclusion is bounded by actual evidence.
|
||||
|
||||
## Reference
|
||||
|
||||
- [ ] The rule is reusable beyond the originating incident.
|
||||
- [ ] It is not the Case summary rewritten declaratively.
|
||||
- [ ] Scope and exception can be stated from sources.
|
||||
|
||||
## Open Question
|
||||
|
||||
- [ ] The answer is not already in the analysis.
|
||||
- [ ] Known/unknown/next verification are separable.
|
||||
- [ ] Candidate options are included only when sources really considered them.
|
||||
|
||||
## Decision
|
||||
|
||||
- [ ] A project choice is explicitly recorded or user-supplied.
|
||||
- [ ] `technology is present` is not being treated as rationale.
|
||||
- [ ] `NEEDS_DECISION` is used if the direction is only a recommendation.
|
||||
|
||||
## Duplication
|
||||
|
||||
- [ ] No two nodes have the same primary purpose.
|
||||
- [ ] Relations are used instead of copying one record's entire content into another.
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
name: refactoring-from-analysis
|
||||
description: Use when a completed codebase analysis should be turned into one bounded, evidence-backed refactoring WorkItem and implemented in isolation.
|
||||
---
|
||||
|
||||
# Refactoring From Analysis
|
||||
|
||||
## Goal
|
||||
|
||||
Use `docs/<프로젝트>` as high-value context for a bounded refactor while treating the current `<분석 대상 저장소>` as source truth. One execution handles at most one WorkItem.
|
||||
|
||||
## Required sequence
|
||||
|
||||
1. Read `<분석 대상 저장소>/refactor-queue.yaml` and the selected `docs/<프로젝트>/refactor/<project>/<item>/work-item.json`.
|
||||
2. Read the project's completed `document-detail` analysis and source anchors cited by the WorkItem.
|
||||
3. Confirm the analysis queue entry is `COMPLETE`, its completed source revision equals current repository HEAD, and the source working tree is clean. Otherwise do not refactor.
|
||||
4. Re-check the finding against current code. If it no longer exists, mark the item `REJECTED` with evidence; do not force a change.
|
||||
5. Read `references/refactor-queue-contract.md`, `references/work-item-contract.md`, `references/type-strategies.md`, and `references/evidence-contract.md`. For `PERFORMANCE`, also read `references/performance-evidence-contract.md`.
|
||||
6. Create/use an isolated Git worktree/branch for the WorkItem. Never implement directly in the analysis source checkout.
|
||||
7. Follow the strategy selected by `type` and `scope`.
|
||||
8. Preserve raw verification evidence under `docs/<프로젝트>/refactor/<project>/<item>/`.
|
||||
9. Run `scripts/verify-refactor-work-item.py <item-dir>` before moving to `WAITING_APPROVAL`.
|
||||
|
||||
## Performance ordering rule
|
||||
|
||||
For `PERFORMANCE`, the state/operation sequence is mandatory:
|
||||
|
||||
`READY → BASELINING → baseline capture at analysisRevision → IN_PROGRESS → source change → VERIFYING → after capture under the same measurement contract → comparison → functional regression checks → WAITING_APPROVAL`.
|
||||
|
||||
`IN_PROGRESS` means source-changing work is now allowed, so a performance item may not enter it until baseline raw evidence and baseline metadata exist. No source-changing refactor begins before that baseline exists. If comparable measurement conditions cannot be maintained, mark the item `BLOCKED` or the comparison `INCOMPARABLE`; never claim improvement.
|
||||
|
||||
## Bounded change rule
|
||||
|
||||
If a WorkItem expands beyond its declared scope or uncovers an independent problem, stop expanding the diff. Create another candidate WorkItem instead. A large project or module is not permission for a large refactor item.
|
||||
@@ -0,0 +1,20 @@
|
||||
# Refactoring Evidence Contract
|
||||
|
||||
Every WorkItem retains enough evidence for another reviewer or later Tech Log reanalysis to answer:
|
||||
|
||||
1. What source revision was analyzed?
|
||||
2. What exact problem was confirmed in current code?
|
||||
3. What changed?
|
||||
4. What commands/tests/measurements were run?
|
||||
5. What raw outputs support the result?
|
||||
6. What conditions or limitations apply?
|
||||
|
||||
Store:
|
||||
|
||||
- execution/measurement environment;
|
||||
- raw baseline and after output when the type requires comparison;
|
||||
- functional/architecture/integration verification output;
|
||||
- changed-file/diff summary;
|
||||
- explicit acceptance result and limitations.
|
||||
|
||||
Evidence is append-only for a completed cycle where practical. Do not replace a failed raw run with only the successful run; retain material failed attempts when they explain the final result. Never store secrets.
|
||||
@@ -0,0 +1,37 @@
|
||||
# Performance Evidence Contract
|
||||
|
||||
A performance refactor is not complete because code looks faster. It needs a comparable before/after experiment.
|
||||
|
||||
## Lifecycle
|
||||
|
||||
A performance item uses `READY → BASELINING → IN_PROGRESS → VERIFYING → WAITING_APPROVAL`. `BASELINING` is measurement-only. Source changes are forbidden until the baseline at `analysisRevision` has been retained and the item moves to `IN_PROGRESS`.
|
||||
|
||||
## Before code changes
|
||||
|
||||
Freeze the measurement contract in `work-item.json`:
|
||||
|
||||
- exact command or reproducible procedure;
|
||||
- cwd;
|
||||
- environment record;
|
||||
- dataset/fixture/load profile;
|
||||
- warmup and iteration policy when relevant;
|
||||
- metrics and units;
|
||||
- acceptance criteria.
|
||||
|
||||
Capture baseline raw output under `evidence/baseline/raw/` and fill `evidence/baseline/metadata.json` with source revision, command, cwd, exit code, dataset, metrics, and raw file references.
|
||||
|
||||
## After code changes
|
||||
|
||||
Use the same measurement contract. Capture raw output under `evidence/after/raw/` and the matching metadata file.
|
||||
|
||||
## Comparison
|
||||
|
||||
`evidence/comparison.md` must state whether conditions are materially equivalent and list baseline, after, delta, acceptance result, functional regression checks, conclusion, and limitations.
|
||||
|
||||
Allowed conclusions: `IMPROVED`, `NEUTRAL`, `REGRESSED`, `INCOMPARABLE`.
|
||||
|
||||
If command/procedure, metric definition, dataset/load profile, or material environment differs enough to invalidate comparison, use `INCOMPARABLE`. Do not convert incomparable measurements into an improvement claim.
|
||||
|
||||
## Evidence quality
|
||||
|
||||
Retain raw output. A hand-written summary alone is insufficient. Do not fabricate missing runs. Avoid secrets at command construction time rather than relying on later redaction.
|
||||
@@ -0,0 +1,28 @@
|
||||
# Refactor Queue Contract
|
||||
|
||||
`<분석 대상 저장소>/refactor-queue.yaml` is the ordering SSOT for bounded refactoring work.
|
||||
|
||||
## Responsibility split
|
||||
|
||||
- Queue: order, active item, summary state.
|
||||
- `docs/<프로젝트>/refactor/<project>/<item>/work-item.json`: detailed problem, goal, type, scope, acceptance criteria, evidence references.
|
||||
|
||||
## Selection
|
||||
|
||||
1. Ignore items whose analysis snapshot is no longer `COMPLETE`, revision-current, and clean.
|
||||
2. Among actionable `READY` items, lower priority number wins: `P0` → `P1` → `P2` → `P3`.
|
||||
3. For equal priority, file order wins.
|
||||
4. At most one WorkItem is active. Do not start another while the active item is baselining, changing source, verifying, or waiting for approval.
|
||||
5. One scheduled execution works on at most one bounded item.
|
||||
|
||||
## Summary entry shape
|
||||
|
||||
```yaml
|
||||
- project: backend-clean-architecture
|
||||
id: RF-001
|
||||
priority: P1
|
||||
status: READY
|
||||
detail: docs/<프로젝트>/refactor/backend-clean-architecture/RF-001/work-item.json
|
||||
```
|
||||
|
||||
The queue does not duplicate detailed analysis or evidence. If queue summary and `work-item.json` disagree, stop and reconcile instead of guessing.
|
||||
@@ -0,0 +1,28 @@
|
||||
# Refactoring Type Strategies
|
||||
|
||||
Type selects mandatory work and verification. Scope controls how broadly dependencies and regressions must be checked.
|
||||
|
||||
| Type | Mandatory strategy / evidence |
|
||||
|---|---|
|
||||
| PERFORMANCE | Baseline first, same-contract after measurement, before/after comparison, functional regression checks |
|
||||
| BUILD | Baseline/after build measurement when speed/size improvement is claimed; build correctness and task/configuration evidence |
|
||||
| ARCHITECTURE | Boundary/dependency evidence, architecture rules, build and affected integration paths |
|
||||
| MODULE_STRUCTURE | Module/package dependency graph or rule evidence plus affected build/integration tests |
|
||||
| DEPENDENCY | Before/after dependency graph, conflict/API impact, build/test evidence |
|
||||
| DATA_ACCESS | Query/SQL/row/query-count/plan evidence as relevant plus real DB integration when vendor behavior matters |
|
||||
| TRANSACTION | Transaction boundary, commit/rollback/failure contract tests; real provider/DB where semantics depend on it |
|
||||
| CONCURRENCY | Deterministic concurrency/contention tests and failure evidence; do not infer safety from sequential tests |
|
||||
| RELIABILITY | Failure-path/recovery/retry/timeout evidence and regression tests |
|
||||
| SECURITY | Positive and negative-path security tests/config evidence; never retain credentials in evidence |
|
||||
| CODE_STRUCTURE | Behavior-preserving tests, reference scan, build; public contract impact explicitly checked |
|
||||
| CLEANUP | Reference/usage scan proving removal is safe plus build/tests |
|
||||
| TESTABILITY | Demonstrate the targeted behavior is now directly verifiable; preserve production behavior |
|
||||
| CONFIGURATION | Binding/default/conditional-loading tests and affected runtime startup/config evidence |
|
||||
| OPERABILITY | Logs/metrics/health/runtime behavior evidence appropriate to the operational claim |
|
||||
|
||||
## Scope expansion
|
||||
|
||||
- `LOCAL`: verify immediate callers/contract plus relevant tests.
|
||||
- `MODULE`: verify module API, internal dependency edges, module tests/build.
|
||||
- `CROSS_MODULE`: verify all touched module contracts/dependency direction and integration paths.
|
||||
- `PROJECT`: exceptional; requires project-wide impact inventory and broad verification. Prefer decomposition when possible.
|
||||
@@ -0,0 +1,35 @@
|
||||
# Refactoring WorkItem Contract
|
||||
|
||||
`<분석 대상 저장소>/refactor-queue.yaml` determines execution order. `docs/<프로젝트>/refactor/<project>/<item>/work-item.json` owns detail.
|
||||
|
||||
## Required fields
|
||||
|
||||
- `id`, `project`, `analysisRevision`
|
||||
- `priority`: P0, P1, P2, P3
|
||||
- `type`: one supported strategy type
|
||||
- `scope`: LOCAL, MODULE, CROSS_MODULE, PROJECT
|
||||
- `target`, `problem`, `goal`
|
||||
- `acceptanceCriteria`
|
||||
- `status`
|
||||
- evidence references
|
||||
|
||||
Priority decides order. Type and scope decide how work is executed and verified.
|
||||
|
||||
## Statuses
|
||||
|
||||
Allowed statuses are `CANDIDATE`, `READY`, `BASELINING`, `IN_PROGRESS`, `VERIFYING`, `WAITING_APPROVAL`, `APPROVED`, `MERGED`, `REJECTED`, `BLOCKED`, and `COMPLETE`.
|
||||
|
||||
`BASELINING` is used by performance work before source modification. Other types normally move from `READY` directly to `IN_PROGRESS`.
|
||||
|
||||
## Eligibility
|
||||
|
||||
Before changing code:
|
||||
|
||||
- analysis queue status is `COMPLETE`;
|
||||
- `analysisRevision` equals the completed analysis source revision;
|
||||
- current repository HEAD equals that revision;
|
||||
- source checkout is clean;
|
||||
- the finding still exists in current code;
|
||||
- item is bounded enough to review independently.
|
||||
|
||||
If any source revision differs, the refactor is not eligible; reanalysis is required first.
|
||||
@@ -33,6 +33,37 @@ Before the first rewrite in a task, read both references:
|
||||
Read the complete source and the nearby context needed to interpret pronouns, comparisons, and causes.
|
||||
Do not rewrite an isolated paragraph when its protected meaning depends on the surrounding section.
|
||||
|
||||
## Required sequence
|
||||
|
||||
This is an **editorial** pass. The source's facts, evidence, causal chain, uncertainty, decision status,
|
||||
and technical depth are the contract. Work in this order — the steps that have their own section are
|
||||
named here so the spine stays visible.
|
||||
|
||||
1. **Read the whole record once without editing.** A paragraph fixed before you know how the piece ends
|
||||
is fixed against the wrong context.
|
||||
2. **Mark the protected literals and the sentences that carry technical weight** — `Establish the meaning
|
||||
contract` below, and `references/protected-content.md`.
|
||||
3. **Name the stylistic problems, and only those.** Repeated sentence frames, forced conversational tone,
|
||||
abstract filler, too many headings, translated constructions, a conclusion restated in three places,
|
||||
paragraphs of identical length, bolding that has stopped meaning anything.
|
||||
4. **Edit diction, sentence order inside a paragraph, paragraph boundaries, and headings.** Do not move a
|
||||
fact between sections while doing it.
|
||||
5. **Re-read against the original** and restore every technical fact, limitation, condition, and evidence
|
||||
detail that fell out. This step finds more than it seems it should.
|
||||
6. **Close with `Mechanical pass` then `Final check`.** The checkers read surface patterns; the read-aloud
|
||||
test and the preservation questions decide.
|
||||
|
||||
### Hard rules for this pass
|
||||
|
||||
- Do not shorten merely to look more human.
|
||||
- **Do not remove implementation detail because the paragraph feels dense.** Density is not a style defect.
|
||||
- Do not create `처음에는`, `해보니`, `놀랍게도`, `저희는` or other experience language unless the source
|
||||
records that experience.
|
||||
- **Do not imitate one company's or one author's voice.** `style_profile.mjs` measures against five
|
||||
Woowahan articles because they are a *sample of engineering writing*, not a target to sound like. Apply
|
||||
the cross-source patterns in `references/editorial-rules.md`; do not adopt a house style.
|
||||
- Do not make every section equally polished, equally long, or structurally symmetric.
|
||||
|
||||
## Establish the meaning contract
|
||||
|
||||
Make an internal claim ledger before editing. Do not print it unless asked. Record:
|
||||
@@ -444,6 +475,20 @@ remove.
|
||||
Clean output does not mean the rewrite is good. Both tools read surface patterns and cannot see meaning;
|
||||
every rule above still applies, and the read-aloud test below is the one that decides.
|
||||
|
||||
## 참조
|
||||
|
||||
- `references/regression-examples.md` — 고친 예와 실패 이유
|
||||
- `references/protected-content.md` — 옮길 때 한 글자도 바꾸면 안 되는 것
|
||||
- `references/editorial-rules.md` — 편집 규칙
|
||||
- `references/research-method.md` — 문체 기준값을 다시 재는 방법
|
||||
- `references/corpus/` — 한국어 기술 글 코퍼스 조사 노트
|
||||
|
||||
문장 규칙 두 개는 `writing-tech-log-records` 스킬에 있다. 두 스킬이 같은 규칙을 쓰므로 사본을
|
||||
만들지 않는다.
|
||||
|
||||
- `../writing-tech-log-records/references/explaining.md` — 설명하는 법
|
||||
- `../writing-tech-log-records/references/ai-tells.md` — 문서군 전체의 리듬
|
||||
|
||||
## Final check
|
||||
|
||||
First, read every rewritten sentence aloud and ask: **would a Korean-speaking developer say this to a
|
||||
|
||||
+78
@@ -0,0 +1,78 @@
|
||||
# 2026-08-28 Korean Engineering Blog Corpus Notes
|
||||
|
||||
## 조사 범위
|
||||
|
||||
공개된 한국 기술 블로그 중 실제 서비스/시스템 개발 경험을 다루는 글을 중심으로 보았다.
|
||||
|
||||
- NAVER D2 — 「네이버 통합 검색의 웹 성능 - 모니터링과 성능 개선」, 「생성형 AI 기반 실시간 검색 결과 재순위화 1편」, 검색 SRE 관련 글
|
||||
- 토스 기술 블로그 — 토스증권 실시간 데이터 파이프라인/Observability 시리즈, Gateway 관련 글
|
||||
- 우아한형제들 기술블로그 — 장시간 비동기 작업을 Kafka에서 RDB Task Queue로 재설계한 글, Kafka/분산락/개발환경 관련 글
|
||||
- 카카오테크 — 서버 개발자를 위한 운영툴 개발 등 실제 개발/운영 경험 글
|
||||
|
||||
이 문서는 표현을 복사하는 자료가 아니라 공통 구조를 추출한 메모다.
|
||||
|
||||
## 반복해서 보인 서술 관행
|
||||
|
||||
### 1. 기술 이름보다 서비스 상황과 제약이 먼저 나온다
|
||||
|
||||
글이 곧바로 프레임워크 장점을 나열하기보다 현재 시스템 규모, 기존 구조, 실제 운영 요구나 실패 상황을 먼저 설명한다. 기술 선택은 그 뒤의 문제 해결 수단으로 등장한다.
|
||||
|
||||
편집 기준: 초안이 `X는 무엇인가`로 길게 시작하지만 실제 사건이 뒤에 있다면, 필요한 개념 설명만 남기고 사건/제약을 앞쪽으로 이동한다.
|
||||
|
||||
### 2. 해결책 전에 요구조건을 명시한다
|
||||
|
||||
토스의 Observability 글과 우아한형제들의 장시간 작업 재설계 글처럼 해결안이 만족해야 할 조건을 목록/표로 먼저 고정하는 패턴이 자주 보인다. 이러면 선택 이유가 일반론이 아니라 제약과 연결된다.
|
||||
|
||||
편집 기준: 선택을 설명할 때 자료에 있는 `제약 → 요구조건 → 선택` 연결을 살린다. 자료에 없는 요구조건을 새로 만들지는 않는다.
|
||||
|
||||
### 3. 문제는 관측된 현상과 원인 추적으로 이어진다
|
||||
|
||||
NAVER D2의 웹 성능 글은 배포 시점의 변화, 지표, 원인 후보를 실제 관측 흐름에 연결한다. 우아한형제들의 Kafka 작업 글도 처리시간 증가 → poll 공백 → rebalance → 중복 처리로 사건을 이어 간다.
|
||||
|
||||
편집 기준: `문제가 있었다` 뒤에 추상 평가를 늘리지 말고, 입력/상태 변화/관측 결과/원인 근거를 이어 쓴다.
|
||||
|
||||
### 4. 수치는 주장 장식이 아니라 비교 축이다
|
||||
|
||||
성능 수치나 규모가 나오면 무엇과 무엇을 비교하는지, 어느 시점/조건에서 측정했는지가 같이 나온다. 숫자만 굵게 강조해 결론을 대신하지 않는다.
|
||||
|
||||
편집 기준: 수치 근처에 측정 조건과 비교 대상을 유지한다. 근거 없는 정량 표현은 삭제한다.
|
||||
|
||||
### 5. 표와 그림은 산문을 대신할 축이 있을 때 쓴다
|
||||
|
||||
요구사항, 전/후 비교, 구성요소, 여러 후보의 동일한 비교축처럼 행/열이 자연스러운 경우 표를 쓴다. 그림은 구조나 흐름을 보여주고, 본문은 그림에서 읽어야 할 변화나 의미를 설명한다.
|
||||
|
||||
### 6. 실제 글은 모든 절의 길이와 문형이 같지 않다
|
||||
|
||||
배경은 짧고 핵심 실패 원인은 길 수 있으며, 자명한 결과는 한두 문장으로 끝난다. 모든 절을 `문제 → 원인 → 해결 → 장점` 네 문장으로 맞추지 않는다.
|
||||
|
||||
### 7. 1인칭은 실제 경험을 담을 때만 자연스럽다
|
||||
|
||||
기업 기술 블로그는 `저희는`, `우리는`을 자주 쓰지만 이는 실제 작성자가 겪은 프로젝트 경험이 있기 때문이다. 코드 분석에서 그런 기록이 없는데 같은 장치를 흉내 내면 오히려 가짜 경험이 된다.
|
||||
|
||||
편집 기준: source에 1인칭 경험이 없으면 객관적 관측 문장으로 쓴다.
|
||||
|
||||
### 8. 한계를 숨기지 않는다
|
||||
|
||||
새 구조가 해결한 범위와 아직 남은 문제를 분리하는 글이 많다. 이것이 기술 선택을 과장하지 않게 만든다.
|
||||
|
||||
편집 기준: 상세 분석의 `확인하지 않은 것`, `남은 질문`, `운영에서 별도 검증할 것`을 삭제하지 않는다.
|
||||
|
||||
### 9. 개념 설명은 현재 문제를 읽는 데 필요한 만큼만 끼워 넣는다
|
||||
|
||||
Kafka, Gateway, LCP 같은 용어를 설명하더라도 백과사전식 장문이 아니라 이후 구조/문제를 이해하는 데 필요한 수준으로 제한한다.
|
||||
|
||||
### 10. 제목은 읽을 이유를 주되 본문보다 앞서 결론을 과장하지 않는다
|
||||
|
||||
문제/구조/변화를 드러내는 제목은 많지만, 모든 절을 질문형이나 자극적인 카피로 만들지는 않는다. 핵심 기술 문단은 비교적 직접적이다.
|
||||
|
||||
## 조사한 공개 글
|
||||
|
||||
- NAVER D2 — 네이버 통합 검색의 웹 성능 - 모니터링과 성능 개선: https://d2.naver.com/helloworld/8113611
|
||||
- NAVER D2 — 생성형 AI 기반 실시간 검색 결과 재순위화 1편: https://d2.naver.com/helloworld/2380720
|
||||
- 토스 기술 블로그 — 토스증권의 수 천개 실시간 데이터 파이프라인 운영방법 #2: https://toss.tech/article/MSA-observability
|
||||
- 토스 기술 블로그 — 토스는 Gateway 이렇게 씁니다: https://toss.tech/article/22910
|
||||
- 우아한형제들 기술블로그 — 장시간 비동기 작업, Kafka 대신 RDB 기반 Task Queue로 해결하기: https://techblog.woowahan.com/23625/
|
||||
- 우아한형제들 기술블로그 — 표준 개발 환경 개선 되돌아보기: https://techblog.woowahan.com/15572/
|
||||
- 카카오테크 — 서버 개발자를 위한 운영툴 개발: https://tech.kakao.com/posts/528
|
||||
|
||||
URL은 조사 provenance를 남기기 위한 것이다. 특정 문장을 복사하거나 특정 필자의 어조를 목표로 삼지 않는다.
|
||||
@@ -0,0 +1,7 @@
|
||||
# Korean Technical Writing Research
|
||||
|
||||
한국어 엔지니어링 글의 편집 기준을 만들기 위한 공개 자료 조사 기록을 둔다.
|
||||
|
||||
목적은 특정 회사나 필자의 문체를 복제하는 것이 아니다. 여러 기술 블로그에서 반복되는 **문제 제시, 근거 전개, 요구사항 명시, 측정 결과 연결, 한계 표기, 표/그림 사용 방식**을 추출해 `humanizing-korean-tech-writing` Skill에 반영한다.
|
||||
|
||||
새 조사 결과는 날짜별 corpus note에 먼저 기록하고, 여러 출처에서 반복되는 패턴만 Skill의 durable rule로 승격한다.
|
||||
@@ -19,7 +19,7 @@
|
||||
- [검색 성능 개선을 위한 Elasticsearch 인덱스 구조와 쿼리 최적화](https://techblog.woowahan.com/20161/) — `20161`
|
||||
- [나 4년 차 서버개발자, 배달의민족의 지리 체계를 뒤흔들다](https://techblog.woowahan.com/11238/) — `11238`
|
||||
|
||||
이 다섯 편은 `scripts/style_profile.mjs`가 쓰는 기준선이기도 하다. 원문을 다시 받으려면
|
||||
이 다섯 편은 `scripts/style_profile.mjs`가 문체 수치를 재는 기준값이기도 하다. 원문을 다시 받으려면
|
||||
`node scripts/fetch_reference.mjs <디렉터리>`를 쓴다. 사이트가 curl과 리더 프록시를 403으로 막으므로
|
||||
실제 브라우저가 필요하고, `playwright-core`가 있어야 한다. 받은 뒤
|
||||
`node scripts/style_profile.mjs --baseline <디렉터리>/*.md`로 값을 다시 잰다.
|
||||
|
||||
@@ -0,0 +1,72 @@
|
||||
# Editorial Rules From Korean Engineering Writing
|
||||
|
||||
These rules were distilled from multiple public Korean engineering blogs. They describe broad technical-writing habits, not a target author's style.
|
||||
|
||||
## Lead with the engineering situation
|
||||
|
||||
When a draft spends several paragraphs defining a technology before stating why it appears, move the concrete service/code situation, constraint, failure, or measurement earlier. Keep only the concept explanation needed to follow that situation.
|
||||
|
||||
Do not fabricate a `background story` merely to create an opening.
|
||||
|
||||
## Keep constraint → requirement → choice connected
|
||||
|
||||
A credible choice is usually readable from its constraints. When the source contains requirements, put them close to the solution they rule in/out. Do not add generic benefits such as maintainability, scalability, security, or performance unless the source demonstrates that they mattered here.
|
||||
|
||||
## Write the observed chain, not a summary slogan
|
||||
|
||||
Prefer:
|
||||
|
||||
```text
|
||||
input/condition → state change → observable result → evidence-backed cause
|
||||
```
|
||||
|
||||
over a paragraph that repeatedly says the architecture has a problem or responsibility.
|
||||
|
||||
## Make metrics carry context
|
||||
|
||||
Keep the dataset, request shape, time window, before/after condition, or comparison axis next to a number. Do not turn a measurement into an adjective such as `크게`, `압도적으로`, `획기적으로` unless the source justifies that interpretation.
|
||||
|
||||
## Use tables only when there is a real axis
|
||||
|
||||
Good table candidates:
|
||||
|
||||
- requirement → reason;
|
||||
- before → after;
|
||||
- option → same comparison dimensions;
|
||||
- environment → observed result;
|
||||
- defined → not defined verification coverage.
|
||||
|
||||
If every row needs a paragraph of caveats, prose may be clearer.
|
||||
|
||||
## Let section lengths differ
|
||||
|
||||
Human engineering reports spend space where the difficult reasoning occurred. A two-line setup next to a long failure analysis is fine. Do not normalize all sections to the same number of paragraphs or bullets.
|
||||
|
||||
## Do not manufacture first person
|
||||
|
||||
Public engineering blogs often use first person because their authors participated in the project. A code-derived document has no such license. Use `코드에서는`, `실행 결과에서는`, `이 구성에서는`, or the concrete component name unless source material contains a real first-person account.
|
||||
|
||||
## Preserve limitations
|
||||
|
||||
Do not polish away `확인하지 않은 것`, `운영에서는 별도 검증`, failed attempts, excluded scope, or competing explanations. Those boundaries make the technical claim credible.
|
||||
|
||||
## Explain concepts at the point of use
|
||||
|
||||
Introduce PKCE, LCP, Kafka rebalance, keyset pagination, etc. only to the depth needed for the next piece of reasoning. Avoid detached encyclopedia sections unless the record itself is a Reference that requires them.
|
||||
|
||||
## Prefer direct headings over forced questions
|
||||
|
||||
Use headings that name the actual event, boundary, measurement, or change. Do not convert every heading to `왜 ...일까?`, `...해보자`, or rhetorical copy. A question heading is appropriate only when the section genuinely resolves that question.
|
||||
|
||||
## Vary rhythm by content, not by randomization
|
||||
|
||||
Do not mechanically alternate short and long sentences. Instead:
|
||||
|
||||
- keep a consequence close to its cause;
|
||||
- split a sentence when it contains two independently important actions;
|
||||
- keep a short sentence when a measured fact can stand alone;
|
||||
- combine fragments that only make sense together.
|
||||
|
||||
## Remove AI scaffolding
|
||||
|
||||
Review expressions such as `중요한 점은`, `핵심은`, `결국`, `즉`, `다시 말해`, `이 지점에서`, `한편`, `정리하면`. They are not forbidden, but repeated use often means the previous sentence already said the same thing. Delete the scaffold before rewriting the substance.
|
||||
@@ -0,0 +1,33 @@
|
||||
# Protected Content
|
||||
|
||||
Editorial work must preserve these exactly unless the source itself is being corrected with new evidence:
|
||||
|
||||
- numeric values and signs;
|
||||
- dates and times;
|
||||
- versions;
|
||||
- units;
|
||||
- commands and command arguments;
|
||||
- code and configuration;
|
||||
- file/module/class/method names when used as identifiers;
|
||||
- URLs and paths;
|
||||
- HTTP status/error codes;
|
||||
- test names and assertions;
|
||||
- observed terminal/browser output;
|
||||
- direct quotations;
|
||||
- decision/question status;
|
||||
- distinctions between observed fact, inference, assumption, unknown, and recommendation.
|
||||
|
||||
## Meaning-preservation checks
|
||||
|
||||
After editing, compare original and revised record and ask:
|
||||
|
||||
1. Did any condition (`when`, `only if`, environment, topology, dataset) disappear?
|
||||
2. Did `can/may` become `does/will`?
|
||||
3. Did a local/test observation become a production/general claim?
|
||||
4. Did an unresolved question sound answered?
|
||||
5. Did a proposed decision sound adopted?
|
||||
6. Did a measured value lose its measurement context?
|
||||
7. Did a failure/limitation disappear because it made the paragraph less tidy?
|
||||
8. Did the rewrite invent a motivation or personal history?
|
||||
|
||||
If yes, restore the lost distinction before further stylistic changes.
|
||||
@@ -0,0 +1,10 @@
|
||||
# Research Method
|
||||
|
||||
Use this when updating the editorial skill from public Korean engineering writing.
|
||||
|
||||
1. Sample several companies and several technical domains; do not build rules from one writer.
|
||||
2. Prefer implementation/incident/performance/operations articles over recruiting or marketing posts.
|
||||
3. Record structural observations: how the problem is introduced, where constraints appear, how measurements are tied to claims, how alternatives and limitations are handled, and when tables/diagrams replace prose.
|
||||
4. Do not copy distinctive phrases, jokes, metaphors, or signature expressions.
|
||||
5. Promote a pattern into `editorial-rules.md` only when it appears useful across multiple sources and is compatible with evidence-preserving Tech Log writing.
|
||||
6. Keep source notes under `./research/korean-tech-writing/`; runtime editing must work even if the websites are unavailable later.
|
||||
@@ -62,7 +62,12 @@ const ACRONYM_OK = new Set([
|
||||
function strip(src) {
|
||||
return src
|
||||
.replace(/```[\s\S]*?```/g, (m) => m.replace(/[^\n]/g, ' '))
|
||||
.replace(/`[^`\n]*`/g, (m) => ' '.repeat(m.length));
|
||||
.replace(/`[^`\n]*`/g, (m) => ' '.repeat(m.length))
|
||||
// 표와 인용은 「쓰지 않는다」 예시가 사는 자리다. 규칙을 적은 문서가 그 규칙을 어긴 것으로
|
||||
// 잡히지 않게 줄을 통째로 비운다. 줄 번호는 유지한다.
|
||||
.split('\n')
|
||||
.map((line) => (/^\s*(\||>)/.test(line) ? ' '.repeat(line.length) : line))
|
||||
.join('\n');
|
||||
}
|
||||
|
||||
function positiveChecks(text, lines, docMode, rulesMode) {
|
||||
|
||||
@@ -11,6 +11,7 @@ Tech Log Studio에 올릴 기록을 쓰는 스킬. Case · Concept · Reference
|
||||
| `references/record-kinds.md` | 다섯 종류의 칸·상한·게시 조건 |
|
||||
| `references/from-ssot-to-records.md` | 긴 글에서 글감을 뽑는 기준과 `tech-log-tree.json` |
|
||||
| `references/writing-each-kind.md` | 종류마다 무엇을 어떤 순서로 쓰나 |
|
||||
| `templates/*.md` | 종류별 빈 틀. 복사해서 채운다 |
|
||||
| `references/body-syntax.md` | Case 본문의 허용·금지 문법 |
|
||||
| `references/code-tables-diagrams.md` | 코드블록·표·SVG·이미지 |
|
||||
| `references/explaining.md` | 설명의 깊이와 말투 |
|
||||
|
||||
@@ -108,3 +108,16 @@
|
||||
- [ ] 게시 후 공개 페이지를 열어 표·코드·그림이 의도대로 나오는지 봤다
|
||||
|
||||
마지막 항목을 건너뛰지 않는다. 저장은 통과해도 공개 화면에서 다르게 보이는 경우가 있다.
|
||||
|
||||
## 분석에서 뽑아 쓸 때 (document-detail 계약)
|
||||
|
||||
- [ ] 이 글감의 `readiness` 가 글을 써도 되는 상태인가
|
||||
- [ ] 모든 실질 주장이 분석·출처·증거 앵커 하나로 되짚어지는가
|
||||
- [ ] 추론을 관측한 것처럼 적지 않았는가
|
||||
- [ ] 로컬·테스트에서 본 것을 운영 사실로 올리지 않았는가
|
||||
- [ ] Case 가 개념 설명이 아니라 구체적인 사건·검증 절차인가
|
||||
- [ ] Reference 가 짝이 되는 Case 의 서사를 통째로 되풀이하지 않는가
|
||||
- [ ] Decision 에 근거가 하나 이상 있고, 무엇을 보고 정했는지가 적혀 있는가
|
||||
- [ ] 지어낸 경험·실패·동기·감정이 없는가
|
||||
- [ ] 그림이 실제 asset 파일을 가리키고, 있어야 할 이유가 있는가
|
||||
- [ ] 그림이 관측하지 않은 사건을 만들어 내지 않았는가
|
||||
|
||||
@@ -0,0 +1,119 @@
|
||||
# Root Tree Contract
|
||||
|
||||
The root tree is the explicit boundary between deep project analysis and Tech Log record generation.
|
||||
|
||||
## Required document header
|
||||
|
||||
A root tree records:
|
||||
|
||||
- `schemaVersion`
|
||||
- `project`
|
||||
- `sourceDocument`
|
||||
- `sourceDocumentSha256`
|
||||
- `sourceRevision`
|
||||
- `generatedAt`
|
||||
|
||||
The hash/revision prevents a scheduled generator from treating a tree derived from old code as current.
|
||||
|
||||
## Required human-readable tree
|
||||
|
||||
Each Topic has a title, slug, and four branches:
|
||||
|
||||
```text
|
||||
PROJECT
|
||||
<project>
|
||||
|
||||
TOPIC
|
||||
<Topic title>
|
||||
<topic-slug>
|
||||
|
||||
├── CASE
|
||||
├── REFERENCE
|
||||
├── OPEN QUESTION
|
||||
└── DECISION
|
||||
```
|
||||
|
||||
Empty branches are allowed. Do not manufacture nodes to fill all four kinds.
|
||||
|
||||
## Node source contract
|
||||
|
||||
Every candidate includes a specification after the human-readable tree.
|
||||
|
||||
### Case
|
||||
|
||||
Required:
|
||||
|
||||
- `slug`
|
||||
- `readiness`
|
||||
- one or more `source` anchors
|
||||
- `classification` explaining the concrete incident/experiment/diagnosis
|
||||
- relevant code/evidence when the conclusion depends on them
|
||||
- `missing-verification`
|
||||
- `relations`
|
||||
|
||||
A Case with `NEEDS_EVIDENCE`, `BLOCKED`, or `REJECTED` is not generated.
|
||||
|
||||
### Reference
|
||||
|
||||
Required:
|
||||
|
||||
- `slug`
|
||||
- `readiness`
|
||||
- `source`
|
||||
- `classification` explaining the reusable criterion
|
||||
- `scope`
|
||||
- `exceptions`
|
||||
- `relations`
|
||||
|
||||
A Reference must be useful beyond retelling one Case. If removing the originating project's names leaves no rule, it is probably still a Case.
|
||||
|
||||
### Open Question
|
||||
|
||||
Required:
|
||||
|
||||
- `slug`
|
||||
- `readiness: OPEN`
|
||||
- `source`
|
||||
- `known`
|
||||
- `unknown`
|
||||
- `next-verification`
|
||||
- `decision-criterion`
|
||||
- `relations`
|
||||
|
||||
Do not generate a Question when the detailed analysis already contains a verified answer. Move the material to Case/Reference/Decision as appropriate and update the tree first.
|
||||
|
||||
### Decision
|
||||
|
||||
Required:
|
||||
|
||||
- `slug`
|
||||
- `readiness`
|
||||
- `decision-status`
|
||||
- `source`
|
||||
- `decision-evidence`
|
||||
- `grounds`
|
||||
- `classification`
|
||||
- `relations`
|
||||
|
||||
`decision-status` is one of `PROPOSED`, `ADOPTED`, `SUPERSEDED`, `NOT_DECIDED`. A `NOT_DECIDED` candidate uses `NEEDS_DECISION` and is not generated as a Decision.
|
||||
|
||||
## Readiness semantics
|
||||
|
||||
| readiness | meaning | generation |
|
||||
|---|---|---|
|
||||
| `READY` | grounded enough for the kind | allowed |
|
||||
| `NEEDS_EVIDENCE` | material assertion still lacks verification | blocked |
|
||||
| `NEEDS_DECISION` | direction sounds plausible but project has not decided | blocked |
|
||||
| `OPEN` | legitimate unresolved Question | allowed as Open Question |
|
||||
| `BLOCKED` | sources are incomplete or contradictory | blocked |
|
||||
| `REJECTED` | should not become a record | blocked |
|
||||
|
||||
## Derivation rules
|
||||
|
||||
1. Start from sections and evidence already present in detailed analysis; do not begin by brainstorming titles.
|
||||
2. Prefer several narrowly grounded Cases over one broad Case that combines unrelated incidents.
|
||||
3. Extract References only after identifying the invariant/selection criterion that survives outside the incident.
|
||||
4. Extract Questions from explicit uncertainty, missing verification, operational unknowns, or conflicting constraints.
|
||||
5. Extract Decisions only from explicit project choice evidence: ADR, commit/history, configuration plus recorded rationale, issue/PR decision, or user-supplied decision record.
|
||||
6. A node may relate to several siblings, but each record has one primary purpose.
|
||||
7. If new runtime evidence changes the answer, update detailed analysis and regenerate/review the tree before editing downstream records.
|
||||
@@ -0,0 +1,49 @@
|
||||
---
|
||||
id: <Studio 가 준 uuid. 아직 없으면 빈 값>
|
||||
kind: CASE
|
||||
slug: <slug>
|
||||
title: <제목>
|
||||
topic: <주제 이름>
|
||||
project: <프로젝트 이름>
|
||||
status: 게시 전
|
||||
studio: "<편집 화면 주소. 아직 없으면 빈 값>"
|
||||
lastVerifiedOn: <실제로 확인한 날 또는 빈 값>
|
||||
assets:
|
||||
- key: <본문의 :::evidence key 와 같은 값>
|
||||
file: <../../../final/assets/… 상대 경로>
|
||||
evidence:
|
||||
- <../../../final/evidence/raw/… 상대 경로>
|
||||
---
|
||||
|
||||
# <title>
|
||||
|
||||
<summary>
|
||||
|
||||
## 관계
|
||||
|
||||
- **<related record>**
|
||||
<why related>
|
||||
|
||||
## 문제
|
||||
|
||||
<concrete observed problem and scope>
|
||||
|
||||
## 결론
|
||||
|
||||
<bounded conclusion supported by evidence>
|
||||
|
||||
## 검증 환경
|
||||
|
||||
<plain text exact environment>
|
||||
|
||||
## 재현 조건
|
||||
|
||||
<ordered concrete conditions/steps>
|
||||
|
||||
## 본문
|
||||
|
||||
<!-- body:start -->
|
||||
|
||||
<rich Case body>
|
||||
|
||||
<!-- body:end -->
|
||||
@@ -0,0 +1,43 @@
|
||||
---
|
||||
id: <Studio 가 준 uuid. 아직 없으면 빈 값>
|
||||
kind: CONCEPT
|
||||
slug: <slug>
|
||||
title: <제목>
|
||||
topic: <주제 이름>
|
||||
project: <프로젝트 이름>
|
||||
status: 게시 전
|
||||
studio: "<편집 화면 주소. 아직 없으면 빈 값>"
|
||||
basisVersion: <무엇을 보고 썼는지. 예 Keycloak 26.7.0 · oidc-client-ts 3.3.0>
|
||||
assets:
|
||||
- key: <본문의 :::evidence key 와 같은 값>
|
||||
file: <../../../final/assets/… 상대 경로>
|
||||
evidence:
|
||||
- <../../../final/evidence/raw/… 상대 경로>
|
||||
---
|
||||
|
||||
# <제목>
|
||||
|
||||
<요약. 이 개념이 무엇을 어떻게 하는지 한 문단>
|
||||
|
||||
## 관계
|
||||
|
||||
- **<이어지는 기록>**
|
||||
<왜 이어지는지>
|
||||
|
||||
## 본문
|
||||
|
||||
<!-- body:start -->
|
||||
|
||||
## <무엇이 무엇을 주고받나>
|
||||
|
||||
<첫 절은 참여자와 오가는 것을 세운다>
|
||||
|
||||
## <단계마다 실제로 일어나는 일>
|
||||
|
||||
## <그 설계가 막지 않는 것>
|
||||
|
||||
## <지금 확인한 범위>
|
||||
|
||||
<규격이 정한 것과 이 구현이 그렇게 한 것을 구분한다. 「확인했다」는 Case 의 말이라 쓰지 않는다>
|
||||
|
||||
<!-- body:end -->
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
id: <Studio 가 준 uuid. 아직 없으면 빈 값>
|
||||
kind: PROJECT_DECISION
|
||||
slug: <slug>
|
||||
title: <제목>
|
||||
topic: <주제 이름>
|
||||
project: <프로젝트 이름>
|
||||
status: 게시 전
|
||||
studio: "<편집 화면 주소. 아직 없으면 빈 값>"
|
||||
decisionStatus: PROPOSED
|
||||
assets:
|
||||
- key: <본문의 :::evidence key 와 같은 값>
|
||||
file: <../../../final/assets/… 상대 경로>
|
||||
evidence:
|
||||
- <../../../final/evidence/raw/… 상대 경로>
|
||||
---
|
||||
|
||||
# <title>
|
||||
|
||||
<summary>
|
||||
|
||||
## 근거
|
||||
|
||||
- **<Case or Reference>**
|
||||
<how it grounds this decision>
|
||||
|
||||
## 결정문
|
||||
|
||||
<the actual project choice>
|
||||
|
||||
## 판단 이유
|
||||
|
||||
<only rationale explicitly supported by decision evidence>
|
||||
|
||||
## 영향
|
||||
|
||||
- <grounded consequence/trade-off>
|
||||
@@ -0,0 +1,51 @@
|
||||
---
|
||||
id: <Studio 가 준 uuid. 아직 없으면 빈 값>
|
||||
kind: QUESTION
|
||||
slug: <slug>
|
||||
title: <제목>
|
||||
topic: <주제 이름>
|
||||
project: <프로젝트 이름>
|
||||
status: 게시 전
|
||||
studio: "<편집 화면 주소. 아직 없으면 빈 값>"
|
||||
questionStatus: OPEN
|
||||
assets:
|
||||
- key: <본문의 :::evidence key 와 같은 값>
|
||||
file: <../../../final/assets/… 상대 경로>
|
||||
evidence:
|
||||
- <../../../final/evidence/raw/… 상대 경로>
|
||||
---
|
||||
|
||||
# <title>
|
||||
|
||||
<summary of unresolved issue>
|
||||
|
||||
## 관계
|
||||
|
||||
- **<related record>**
|
||||
<why related>
|
||||
|
||||
## 사실
|
||||
|
||||
- <grounded fact>
|
||||
|
||||
## 가정
|
||||
|
||||
- <explicit assumption, if any>
|
||||
|
||||
## 미지수
|
||||
|
||||
- <unknown>
|
||||
|
||||
## 제약
|
||||
|
||||
- <constraint>
|
||||
|
||||
## 선택지
|
||||
|
||||
### 1. <grounded candidate, only when it really exists>
|
||||
|
||||
<what is known and what must be checked>
|
||||
|
||||
## 다음 검증
|
||||
|
||||
1. <next concrete verification>
|
||||
@@ -0,0 +1,46 @@
|
||||
---
|
||||
id: <Studio 가 준 uuid. 아직 없으면 빈 값>
|
||||
kind: REFERENCE
|
||||
slug: <slug>
|
||||
title: <제목>
|
||||
topic: <주제 이름>
|
||||
project: <프로젝트 이름>
|
||||
status: 게시 전
|
||||
studio: "<편집 화면 주소. 아직 없으면 빈 값>"
|
||||
assets:
|
||||
- key: <본문의 :::evidence key 와 같은 값>
|
||||
file: <../../../final/assets/… 상대 경로>
|
||||
evidence:
|
||||
- <../../../final/evidence/raw/… 상대 경로>
|
||||
---
|
||||
|
||||
# <title>
|
||||
|
||||
<summary>
|
||||
|
||||
## 관계
|
||||
|
||||
- **<related record>**
|
||||
<why related>
|
||||
|
||||
## 목적
|
||||
|
||||
<why this reusable criterion exists>
|
||||
|
||||
## 규칙
|
||||
|
||||
### 1. <rule title>
|
||||
|
||||
<plain-text rule>
|
||||
|
||||
## 적용 조건
|
||||
|
||||
- <condition>
|
||||
|
||||
## 예외
|
||||
|
||||
- <exception or explicitly none>
|
||||
|
||||
## 예시
|
||||
|
||||
- <plain-text example>
|
||||
Reference in New Issue
Block a user