@uzysjung/agent-harness 26.155.0 → 26.157.0

package/dist/trust-tier-drift.js

@@ -17,7 +17,7 @@ import {
   init_esm_shims,
   residentCost,
   resolveBundleRoot
-} from "./chunk-SC6ORMHV.js";
+} from "./chunk-HHCNPPGS.js";
 
 // src/trust-tier-drift.ts
 init_esm_shims();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uzysjung/agent-harness",
-  "version": "26.155.0",
+  "version": "26.157.0",
   "description": "Curate vetted AI-coding skills & plugins by your tech stack — install only what you need, across Claude Code, Codex, OpenCode & Antigravity",
   "type": "module",
   "publishConfig": {

package/templates/rules/test-policy.md

@@ -6,6 +6,16 @@ belongs to the Delivery rule.
 - An ordinary change gets the repository's baseline CI and regression across the affected scope;
   independent verification only where the Delivery rule requires it. A high-risk one widens that in
   proportion to what it touches and what its failure would cost.
+- Preserve required outcomes with the least burdensome reliable protection.
+  Prefer fixing the cause and reusing or improving existing mechanisms within scope;
+  no new guard is needed when those suffice. Judge safeguards by credible risk,
+  the assurance they add, and total effort, not request emphasis, incident counts,
+  or the number or subject of checks. Tests of safeguards follow the same standard.
+  Reuse valid evidence and recheck affected claims when relevant conditions change.
+  Within project policy, adapt methods to demonstrated model and tool capabilities
+  while preserving acceptance criteria, required gates, and authority boundaries.
+  Finish optional verification when required outcomes have sufficient evidence
+  and residual risk is within the project's accepted limits.
 - High-risk includes at least authentication, authorization, payments and settlement, personal
   data, data integrity, concurrency, state transitions, and migrations.
 - Full regression, full E2E, full mutation, and periodic security scanning belong to the CI/CD
@@ -16,5 +26,7 @@ belongs to the Delivery rule.
   the result. Otherwise, use explicit test doubles or contract tests.
 - Never use unauthorized production personal data, credentials, or secrets in tests.
 - Do not hide failures by weakening assertions, deleting or skipping tests, excluding coverage, or
-  adding indiscriminate retries. Change tests only when the intended behavior has changed.
+  adding indiscriminate retries. Correct or consolidate tests when their expectations are
+  wrong, obsolete, or redundant; preserve coverage of the accepted contract and follow project
+  policy for changes to mandatory gates.
 - If the affected scope cannot be established confidently, broaden the validation.

package/templates/skills/audit-harness-fit/references/audit.md

@@ -107,6 +107,24 @@ for consequential context gaps supported by repeated questions, repository evide
 or a concrete blocked task. Supplement only the actionable information needed to
 resolve the gap, using established references where possible.
 
+Look for guard proliferation where checks duplicate assurance, constrain incidental
+wording or implementation details, or repeatedly confirm another safeguard's
+existence without protecting a consequential outcome. A check's subject, nesting
+depth, or lack of recorded incidents is a review signal, not a removal rule.
+
+For a candidate, identify the required outcome or constraint and the meaningful
+coverage, independence, diagnosis, or recovery value it adds beyond existing
+protection. Consider fixing the cause, repairing or consolidating existing checks,
+replacing a mechanism, narrowing its scope, or retiring it rather than following
+an escalation or downgrade ladder.
+
+Compare the retained quality and credible risk with setup, execution, context,
+false-alarm, review, and maintenance effort. Use qualitative judgment when it
+settles the choice; measure or propose a bounded trial only for uncertainty that
+could change the decision. State unsupported assumptions rather than inventing
+incident probabilities or cost estimates. For consolidation or retirement,
+explain how still-required protection remains covered, or why it is no longer needed.
+
 Choose **keep / rewrite / narrow / supplement / merge / relocate / retire / defer**.
 A useful tool can remain while its wrapper or routing changes. Equivalent content
 under the same scope can establish duplication without an incident or benchmark.

package/templates/skills/audit-harness-fit/references/verification.md

@@ -52,6 +52,21 @@ its assertions and conditions actually support each. Separate targets do not by
 themselves require separate runs or separate reviewers. Add checks for evidence gaps,
 credible risk, or applicable policy; required review independence is a separate issue.
 
+For a new or materially changed executable safeguard, use proportionate evidence
+that it accepts valid operation and detects the relevant violation. Existing tests,
+controlled counterexamples, or another reliable method may suffice. A failing run
+supports the claim only if it fails for the intended reason.
+
+When a check can pass without exercising its intended scope, distinguish that
+condition from a meaningful pass where the contract requires coverage. A known
+violation can exercise detection without proving real-target discovery or required
+execution.
+
+Prefer existing test and execution mechanisms to a new supervisory layer.
+Retain tests of safeguards when they close a meaningful evidence gap; adding a
+check alone creates no need for another. Apply the evidence-reuse, invalidation,
+and stopping guidance below.
+
 Identify binding tests and independent-review gates from their policy / CI source.
 Explicit project policy can bind even without CI enforcement. Preserve those gates;
 route disproportionate mandatory requirements to a separate policy decision. Retain

package/templates/skills/recurrence-prevention/SKILL.md

@@ -3,9 +3,10 @@ name: recurrence-prevention
 description: >-
   When the same defect, mistake, or incident happens AGAIN — a recurrence, not a one-off — verify
   it against prior evidence (memory, rule 근거 links, git/CHANGELOG history), classify it as a
-  simple slip vs a complex harness problem, then escalate the countermeasure one level up the
-  ladder: record (1st) → forced rule with linked priors (2nd) → structural gate — test, hook, or
-  derive — once prose has failed (3rd+). Complex problems get countermeasure candidates designed
+  simple slip vs a complex harness problem, then re-evaluate the countermeasure that failed:
+  repair or replace it, choosing a record, a one-line criterion, a code fix, or a structural gate
+  (test, hook, derive) by evidence — more deterministic when prose has demonstrably failed,
+  nothing new when repair suffices. Complex problems get countermeasure candidates designed
   by a multi-persona panel instead of a quick patch. Use for "재발했어", "같은 실수 또 했네",
   "이거 저번에도 그랬잖아", "재발방지 대책 등록해줘", "재발방지 룰 만들어", "this happened again",
   "same bug as last time", "add a recurrence countermeasure", "postmortem this failure". Do NOT use
@@ -18,15 +19,18 @@ description: >-
 A defect that happens once is a bug. A defect that happens **twice is a countermeasure failure** —
 whatever was supposed to prevent the second occurrence (a mental note, a memory entry, a rule)
 demonstrably did not. So on a recurrence, the unit of work is not the fix (you already know the
-fix — you applied it last time). The unit of work is the **countermeasure**, and the core move is:
-**escalate it one level, because the current level just failed.**
+fix — you applied it last time). The unit of work is the **countermeasure**: re-evaluate the cause
+analysis and whatever was supposed to prevent this, repair or replace it, and reach for a more
+deterministic mechanism only when repairing the existing one cannot suffice. **A recurrence is
+evidence for that re-evaluation, not an order to add a level.**
 
 This skill codifies a practice proven in the harness repo that ships it: the no-false-ship rule
 was created only after the *third* false-ship incident; CHANGELOG drift survived a written
 convention for seven releases and stopped only when a test gate enforced it; comment warnings
 against hardcoded-list drift failed twice before "derive to a single source" became mandatory.
-The pattern is consistent: **each enforcement level fails in a characteristic way, and the answer
-is the next level up — not a louder version of the same level.**
+The pattern is consistent: **each enforcement level fails in a characteristic way, and when one
+has demonstrably failed the answer is usually a more deterministic mechanism — not a louder
+version of the same level, and not a new mechanism when the existing one can be repaired.**
 
 ## When to use
 
@@ -89,7 +93,7 @@ For the capture checklist (what to write down about the failure so the next coun
 | Correct behavior | Known, agreed, undisputed | Disputed, unclear, or trade-off-laden |
 | Why it recurred | Wasn't followed: forgot, skipped, overlooked | The countermeasure itself was wrong/insufficient, or cause spans components |
 | Typical examples | Forgot a checklist step; committed a forbidden file; skipped a verification | A "verified" path that still shipped broken; drift between N surfaces; a gate that passes while the behavior fails |
-| Path | **Escalation ladder** (Step 3a) | **Multi-persona countermeasure design** (Step 3b) |
+| Path | **Choose the countermeasure level** (Step 3a) | **Multi-persona countermeasure design** (Step 3b) |
 
 Two quick discriminators:
 - Could you write the corrective rule in one sentence right now, with confidence nobody would
@@ -103,21 +107,22 @@ When the classification itself is unclear, the cause taxonomy in
 policy · coordination · loop) usually decides it: a `logic`/`state` cause with agreed correct
 behavior is a slip; a `policy`/`coordination` cause is almost always the complex path.
 
-## Step 3a — Simple slip: the escalation ladder
+## Step 3a — Simple slip: choose the countermeasure level
 
-Enter the ladder at the level matching the count. **Never enter above your count** — a gate for a
-first-time slip is gate inflation, and every gate is permanent maintenance + false-positive cost.
-(Two exceptions. Downward-honest: a **registered countermeasure that failed** counts that failure
-at its own level — a violated Level-1 rule at count 2 legitimately escalates to Level 2. And
-cost-driven: the Level 1 pre-flight below sends a count-2 slip straight to Level 2 when the wrong
-action is deterministically detectable, because a gate is the *cheaper* artifact, not the stronger
-one.)
+The levels below are **options ordered by determinism, not a mandatory sequence**. The count is
+evidence of how far the current countermeasure has failed; it does not select the level by itself.
+Choose the least burdensome option that reliably prevents the cause: repair or replace the failed
+countermeasure first; prefer a gate when prose has demonstrably failed or when the wrong action is
+deterministically detectable (a gate is then the *cheaper* artifact, not the stronger one); and
+let credible risk, not the count, justify protection — a concrete irreversible-damage path earns a
+gate at count 0, while a first-time slip with no credible risk earns none (every gate is permanent
+maintenance + false-positive cost).
 
-| Level | When | Countermeasure | Characteristic failure of this level |
+| Level | Typical evidence (a signal, not a trigger) | Countermeasure | Characteristic failure of this level |
 |---|---|---|---|
 | **0 기록** | 1st occurrence | Fix + durable record: memory/lessons entry with **Why** it matters and **How to apply**, or an occurrence link on a related rule's 신설 근거 line if one already exists | Records don't steer — nothing re-reads them at the decision moment |
-| **1 룰 강제 등록** | 2nd occurrence (the record failed) | Register a forced rule on the project's **always-loaded steering surface**, using the template below — one-line principle + a one-line "신설 근거" with links to each occurrence. `.claude/rules/<name>.md` (Claude Code) or a rules section in `AGENTS.md` (other CLIs) — and **verify it actually loads**: if the always-loaded context (CLAUDE.md / AGENTS.md) doesn't already pull that location in, reference the rule from it. A rule file nothing loads is still Level 0 with extra steps | Prose can be skimmed, forgotten under context pressure, or rationalized around |
-| **2 구조적 게이트** | 3rd+ occurrence, **or** a registered countermeasure failed — bypassed *or* followed as designed yet insufficient | Deterministic enforcement that does not depend on the agent reading anything: a test gate that fails CI, a pre-action hook that blocks the command (where the CLI supports hooks), or **derive-to-single-source** so the drift is structurally impossible | Gates that never demonstrably fire; gates so noisy they get bypassed |
+| **1 룰 강제 등록** | 2nd occurrence (the record failed) | Register a forced rule on the project's **always-loaded steering surface**, using the template below — one-line principle + a one-line "신설 근거" with links to each occurrence. `.claude/rules/<name>.md` (Claude Code) or a rules section in `AGENTS.md` (other CLIs) — and **verify it actually loads**: if the always-loaded context (CLAUDE.md / AGENTS.md) doesn't already pull that location in, reference the rule from it. A rule file nothing loads is still Level 0 with extra steps. **Shape**: the *minimum condition* that prevents the failure — what must be true, not how to do it — stated in positive form; a prohibition only where the damage is irreversible | Prose can be skimmed, forgotten under context pressure, or rationalized around |
+| **2 구조적 게이트** | 3rd+ occurrence, **or** a registered countermeasure failed — bypassed *or* followed as designed yet insufficient | Deterministic enforcement that does not depend on the agent reading anything: a test gate that fails CI, a pre-action hook that blocks the command (where the CLI supports hooks), or **derive-to-single-source** so the drift is structurally impossible. **Shape**: a stronger countermeasure means *more deterministic*, not *more forbidden* — the gate checks a result and leaves the model's judgment where no check can express it | Gates that never demonstrably fire; gates so noisy they get bypassed |
 
 Load-bearing principle at Level 2: **comment warnings and doc reminders are not a blocking
 mechanism.** If the countermeasure's effect depends on someone (human or model) reading prose at
@@ -136,27 +141,33 @@ fifth.
 
 **Level 1 pre-flight — a 2nd occurrence does not automatically earn a rule.** Per unit of
 enforcement a rule is the most expensive artifact on the ladder: it is read **every session, by
-every install, forever**, while a gate costs CI time and **zero** standing context. Answer three
+every install, forever**, while a gate costs CI time and **zero** standing context. Answer four
 questions in order and stop at the first that decides:
 
 1. **Can the wrong action be detected deterministically?** — a failing test, a hook that exits
-   non-zero, a derive that deletes the duplicated list. If yes, **write the gate instead, even at
-   count 2.** This is the one sanctioned way to enter above your count, and it is not gate
-   inflation: you are not buying stronger enforcement than the count justifies, you are picking
-   the cheaper artifact for the same enforcement. Code answers what code can answer.
+   non-zero, a derive that deletes the duplicated list. If yes, **write the gate instead of a
+   rule.** That is not gate inflation: you are not buying stronger enforcement than the risk
+   justifies, you are picking the cheaper artifact for the same enforcement. Code answers what
+   code can answer.
 2. **Would the rule change behaviour that would otherwise be wrong?** If the corrective principle
    is something a competent agent does anyway, or it restates a rule that already exists, it buys
    nothing and bills every session. Stay at Level 0.
 3. **Is it general, or is it this project's circumstance?** A project's own incidents belong on
    that project's steering surface — never in a rule set that strangers install.
-
-Only what survives all three — **a judgement call no deterministic check can express, that
-changes behaviour, and that generalises** — is a rule candidate. That is the bar for "serious
+4. **Does the rule replace the model's judgment, or feed it?** A rule that fixes a procedure
+   ("always run X before Y", "review every edit") replaces a judgment the model could make by
+   risk — and stops improving when the model improves. Rewrite it as a one-line criterion (what
+   must be true, what evidence counts) and let the model choose the depth. A rule that removes a
+   place where the model decides is not a rule candidate in that form.
+
+Only what survives all four — **a judgement call no deterministic check can express, that
+changes behaviour, that generalises, and that gives the judgment an input instead of replacing
+it** — is a rule candidate. That is the bar for "serious
 enough to be worth permanent context".
 
 **Confirm before adding standing cost.** Levels 1 and 2 need explicit user confirmation. For a
 rule the escalation must state, in one block: signature · count with evidence · the proposed text ·
-**its standing cost in tokens and the resulting total** · which of the three questions it survived
+**its standing cost in tokens and the resulting total** · **its per-run cost** (seconds, rounds, or questions added to every task — a countermeasure that slows every task to prevent one incident is rejected unless "what actually happens without it" is the answer) · which of the four questions it survived
 and why the deterministic alternative does not work. **Do not guess the cost — measure the draft**
 (if the project reports context cost, run that report). Level 0 needs no confirmation — recording
 a fact is free and always right.
@@ -169,16 +180,18 @@ a fact is free and always right.
 <One-line principle, stated as an imperative.> **신설 근거: N회 재발** (<date/version> ·
 <date/version>) — 발생별 기록은 <issue / ADR / postmortem link per occurrence>.
 
-## 절대 원칙
+## 지켜야 할 상태
 
-**<The enforced behavior. One sentence if possible.>**
-<What is explicitly forbidden, and what to do instead.>
+**<The state that must hold when this rule is followed — positive form, one sentence if possible.>**
+<What breaks it, and what to do instead. A prohibition ("X 금지") belongs here only when X is
+irreversible damage or a protected gate; otherwise state the condition and leave the method to the agent.>
 
 ## 위반 발견 시
 
 1. 즉시 정정 보고 (무엇이 어떻게 위반이었는지 명시)
 2. 발생을 이슈·ADR 에 기록하고 durable memory 에 추가한 뒤, 위 근거 줄의 횟수와 링크를 올린다
-3. 재위반이면 구조적 게이트(테스트/훅/derive)로 승격 — 프로즈는 이미 두 번 실패했다
+3. 재위반이면 원인 분석과 이 룰을 재평가한다 — 룰을 고쳐 충분하면 거기서 끝내고, 프로즈가 실제로
+   실패한 것이면 결정론적 장치(테스트/훅/derive)로 대체한다
 ```
 
 The 근거 line is not decoration — it is the recurrence counter for the *next* occurrence, and it
@@ -201,16 +214,17 @@ for mechanics — run 3-5 personas in parallel, independently, then synthesize):
 - **The adversary** — "this countermeasure will fail because…" for each candidate.
 
 Synthesize into 2-3 concrete countermeasure options with costs, and present them as a decision
-(recommendation first, ASIS→TOBE contrast — see `clear-korean-communication` if bundled). The
+(recommendation first, ASIS→TOBE contrast — see `user-centered-explanation` if bundled). The
 chosen option still lands on the ladder: it becomes a record, a rule, or a gate — the panel decides
-*what* the countermeasure is, the ladder decides *how hard* it is enforced. The
-never-above-your-count guard governs slips with no failed countermeasure; here, a prior
-countermeasure that fired as designed and still failed already justifies landing one level above
-it (a failed Level-1 rule → a Level-2 gate is escalation, not inflation).
+*what* the countermeasure is, the evidence decides *how deterministic* it must be. A prior
+countermeasure that fired as designed and still failed is evidence that repairing it is not
+enough, which justifies a more deterministic mechanism (a failed rule → a gate); it is not a
+mandate to add one — replacing the failed mechanism is the default, stacking a new one on top is not.
 
 When choosing among the panel's options, compare them on prevention strength, false-positive rate,
-standing context cost, maintenance cost, and permission impact — and prefer the *smallest*
-mechanism that actually prevents the cause. The mechanism menu is in
+standing context cost, **per-run speed cost** (time, rounds, and questions added to every task),
+**effect on the model's autonomy** (does it feed a judgment or replace one), maintenance cost, and
+permission impact — and prefer the *smallest* mechanism that actually prevents the cause. The mechanism menu is in
 [references/failure-analysis.md](references/failure-analysis.md).
 
 ## Step 4 — Verify the countermeasure fires
@@ -224,7 +238,7 @@ would be a false ship. Before closing:
   test gate or derive.
 - **Derive/single-source**: show the duplicated site is gone (grep returns one definition).
 - **Rule (prose)**: not mechanically verifiable — say so explicitly ("등록됨, 준수는 미검증").
-  That honesty is what justifies escalating to Level 2 if it recurs anyway.
+  That honesty is what justifies replacing it with a deterministic mechanism if it recurs anyway.
 
 ## Output format — 재발방지 보고
 
@@ -235,8 +249,8 @@ would be a false ship. Before closing:
 - Classification: 단순 실수 | 복잡한 하네스 문제 (+ the discriminator that decided it)
 - Countermeasure: Level 0 기록 | Level 1 룰 | Level 2 게이트 | 페르소나 설계 → <chosen option>
 - Artifact: <path of memory entry / rule file / test or hook>
-- Standing cost: <rule 이면 측정치 ~N tokens/session + 갱신된 총합 | gate·record 면 0>
-- Pre-flight: <Level 1 3질문 통과 근거 — 결정론 불가 사유 · 행동 변화 · 일반성>
+- Standing cost: <rule 이면 측정치 ~N tokens/session + 갱신된 총합 | gate·record 면 0> · per-run: <매 작업에 더해지는 시간·라운드·질문 | 0>
+- Pre-flight: <Level 1 4질문 통과 근거 — 결정론 불가 사유 · 행동 변화 · 일반성 · 판단을 대신하지 않음>
 - Fires-verified: <RED→GREEN output, hook exit code, grep proof — or "룰 프로즈: 미검증" honestly>
 - User confirmation: <obtained for Level 1/2 | not needed (Level 0)>
 ```
@@ -265,15 +279,20 @@ before creating them. Level 0 records need no confirmation.
   is already on the failing trajectory even if no single rule looks unreasonable.
 - **Gate theater** — a gate that was never seen to fire may be checking nothing (wrong matcher,
   wrong path, dead config). Step 4 is mandatory, not optional polish.
+- **Prohibition accumulation** — countermeasures written only as "do not X" pile into a defence
+  list: each blocks one path to the bad state and none of the others, and a model reading a wall
+  of prohibitions either routes around it or freezes. Write the state that must hold; reserve
+  prohibitions for irreversible damage and protected gates.
 - **Same-level retry** — responding to a recurrence by rewriting the same rule more emphatically
-  (CAPS, "NEVER", repetition). The level failed, not the wording. Escalate.
+  (CAPS, "NEVER", repetition). The level failed, not the wording — repair it if it can be
+  repaired, otherwise replace it with a more deterministic mechanism.
 - **Inflating the count** — when no prior artifact can be found, record this as the first confirmed
   occurrence rather than borrowing a remembered one to reach count 2.
 
 ## Cross-references
 
 - `multi-persona-review` — panel mechanics for the complex path (Step 3b).
-- `clear-korean-communication` — presenting countermeasure options for user confirmation
+- `user-centered-explanation` — presenting countermeasure options for user confirmation
   (recommendation first, ASIS→TOBE contrast).
 - **Periodic audit of accumulated countermeasures** — the natural cleanup loop for what this skill
   creates (are the rules and gates still TRUE, USED, AFFORDABLE, SAFE?). No bundled skill owns it;

package/templates/skills/recurrence-prevention/references/failure-analysis.md

@@ -47,17 +47,18 @@ Before designing anything durable, stop the bleeding without widening the blast
 
 ## Countermeasure mechanisms
 
-Prefer the smallest mechanism that prevents the *cause*, not the symptom:
-
-| Cause shape | Mechanism |
-|---|---|
-| Incorrect behavior | Fix the code or the contract |
-| A stable behavioral boundary regressed | Regression test |
-| The same truth is written in two places | Derive from one source (delete the copy) |
-| A deterministic lifecycle event is violated | Hook, or a verification gate |
-| A judgment recurs at decision time and no check can express it | A concise Rule (Level 1) |
-| Completion is claimed without evidence | Verification gate that requires the evidence |
-| Human or external coordination gap | Operating procedure / checklist |
+Prefer the smallest mechanism that prevents the *cause*, not the symptom — and count, for each
+candidate, what it costs on every run and what judgment it takes away from the model:
+
+| Cause shape | Mechanism | Per-run cost | Autonomy impact |
+|---|---|---|---|
+| Incorrect behavior | Fix the code or the contract | none | none |
+| A stable behavioral boundary regressed | Regression test | CI time | none — checks a result, not a method |
+| The same truth is written in two places | Derive from one source (delete the copy) | none (removes work) | none |
+| A deterministic lifecycle event is violated | Hook, or a verification gate | every matching action; a blocking hook adds a round each time it misfires | low if it checks a result; high if it fixes a procedure |
+| A judgment recurs at decision time and no check can express it | A concise Rule (Level 1) | every session (standing context) | feeds the judgment when it states a criterion; replaces it when it fixes a procedure — write the criterion |
+| Completion is claimed without evidence | Verification gate that requires the evidence | per completion claim | none — asks for evidence, not a method |
+| Human or external coordination gap | Operating procedure / checklist | every run of the procedure | high — use only where coordination, not judgment, is the gap |
 
 Verify a mechanical mechanism on **both** the bad case and the corrected case — a gate seen green
 only has never been shown to bite. Record prose-only safeguards as unverified enforcement; that

package/templates/skills/user-centered-explanation/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: user-centered-explanation
+description: >-
+  개발 중 문제·변경안·선택지를 사용자 행동과 결과의 관점에서, 사용자의 언어로 설명한다.
+  맥락·원인·대안·추천 이유를 연결하고,
+  UI/UX 변경은 필요한 화면·문구·동작의 전후 차이를 보여준다.
+  사용자가 "뭔 소리야", "쉽게 설명해줘", "왜 문제야",
+  "사용자에게 뭐가 달라져?", "화면으로 보여줘", "선택지와 추천을 정리해줘"라고 하거나
+  중요한 선택·승인의 차이와 근거를 설명할 때 사용한다.
+  이 스킬만 호출하면 현재 대화의 미해결 문제나 직전 선택 요청을 사용자 관점으로 재정리한다.
+---
+
+# User-Centered Explanation
+
+개발 중 문제와 변경안을 사용자 행동·결과·선택의 관점으로 바꾸어 설명한다.
+사용자가 앞선 대화나 코드를 다시 읽지 않아도 다음을 판단할 수 있게 한다.
+
+**무슨 상황인지 → 무엇이 왜 문제인지 → 어떤 선택지가 있고 무엇이 달라지는지 → 무엇을 추천하며 왜 그런지**
+
+아래 순서·표·예시는 설명을 돕는 기본값이지 고정된 사고·작업 절차가 아니다. 사용자의 목적과 선호 형식을 존중하면서, 설명 깊이·비교 기준·표현 방식은 이해와 판단에 필요한 정보, 읽는 부담, 작업 비용을 고려해 선택한다.
+
+설명과 의사결정을 돕는 스킬이며 작업 범위나 승인 정책 자체를 변경하지 않는다. 답변 언어는 사용자가 쓰는 언어를 따른다.
+
+## 적용
+
+직접 호출되면 현재 대화에서 다음 순서로 대상을 찾는다.
+
+**사용자가 지정한 주제 → 미해결 문제·직전 선택 요청 → 직전 설명**
+
+대화에서 대상을 알 수 있으면 다시 묻지 않는다. 설명할 대상 자체가 없을 때만 원문이나 주제를 요청한다.
+
+직접 호출하거나 중요한 선택·승인을 설명할 때는 아래 기본 표를 우선 사용한다. 기존 형식이 충분히 명확하면 유지한다. 짧은 설명이나 도식이 더 명확하면 판단에 필요한 내용을 유지하면서 항목을 합치거나 표현을 바꿀 수 있다.
+
+직접 호출하지 않은 단순 정보 전달이나 완료 보고는 같은 설명 관점을 유지하되 필요한 내용만 짧게 전달한다.
+
+사용자가 별도 형식을 지정하면 그 형식을 따른다. 어떤 형식이든 **맥락·원인·대안·추천 이유** 중 현재 판단에 필요한 내용이 드러나게 한다.
+
+## 설명 원칙
+
+### 1. 사용자 관점에서 설명한다
+
+파일·함수·오류명보다 먼저 다음을 연결한다.
+
+**사용자가 하려는 일 → 현재 상태 → 문제 또는 제약 → 발생 원인 → 실제 영향**
+
+버그가 아니라 설계 선택, 요구사항 충돌, 환경 제약이라면 그대로 설명한다. 신규 기능은 달성할 목표를, 내부 개선은 직접적인 사용자 변화 여부와 유지보수·운영상의 이유를 설명한다.
+
+설명을 듣는 사람과 실제 영향을 받는 서비스 이용자·관리자·운영자가 다르면 구분한다. 같은 이름이 서로 다른 대상·위치·단계를 가리키면 먼저 구분하고, 실제 영향을 받는 사람의 과업을 기준으로 설명한다.
+
+기술 용어를 쉬운 단어로 바꾸는 데 그치지 않고, 어떤 상황에서 사용자가 무엇을 보거나 할 수 있는지 설명한다.
+
+예: “캐시 무효화를 수정한다”보다 “이름을 바꿔도 목록에는 예전 이름이 남습니다. 저장 후 목록도 최신 이름으로 갱신하도록 고칩니다.”라고 설명한다.
+
+기술 정보는 판단에 필요한 만큼만 사용하고, 낯선 용어는 해당 맥락에서 이해할 수 있게 풀어 쓴다. 정확한 기술명·관련 위치·제약은 필요한 경우 뒤에 덧붙이며, 쉽게 설명하기 위해 의미나 위험을 생략하지 않는다.
+
+### 2. 사실·가설·판단을 구분한다
+
+확인된 사실과 원인, 아직 확인되지 않은 가설, 추천 판단을 섞지 않는다.
+
+이미 확보한 근거가 현재 설명에도 유효하면 재사용한다. 추가 확인은 설명의 정확성이나 선택을 바꿀 수 있는 미확인 사항에 집중하고, 조사·검증의 깊이는 영향과 요청 범위에 맞춘다.
+
+원인이 확인되지 않았다면 원인을 단정하지 말고 다음을 구분한다.
+
+- 확인된 현상과 영향
+- 가능한 원인 또는 가설
+- 방향을 결정하기 위해 추가로 확인할 사항
+
+수치·비용·일정·효과는 근거가 있을 때만 사용한다. 추정치는 가정을 밝히고, 표를 채우기 위해 수치나 대안을 만들지 않는다.
+
+제안·구현·검증·배포 상태를 구분한다. 코드 수정이나 개념 도식만으로 실제 동작·사용성·배포까지 확인된 것처럼 표현하지 않는다.
+
+### 3. 실제 선택 차이를 설명한다
+
+선택지는 개수를 맞추지 말고 실제 선택할 가치가 있는 것만 제시한다. 현상 유지나 보류도 의미 있는 선택이면 포함한다.
+
+각 방안은 다음 차이가 드러나게 설명한다.
+
+**무엇을 하는가 → 왜 해결되는가 → 무엇이 달라지는가 → 어떤 부담이나 위험이 있는가**
+
+비용, 일정, 품질, 사용성, 안전성, 운영 부담 등 실제 결정을 바꾸는 기준에 집중한다.
+
+### 4. 추천은 명확하게 한다
+
+선택이나 조치가 필요할 때는 사용자의 목적과 현재 제약을 기준으로 가장 적합한 방안을 추천한다.
+
+추천에는 다음 중 실제 판단에 영향을 주는 내용을 포함한다.
+
+- 추천하는 이유
+- 다른 방안보다 적합한 이유
+- 감수해야 할 주요 단점
+- 추천을 바꿀 수 있는 중요한 미확인 조건
+
+추천은 판단이지 확인된 사실처럼 표현하지 않는다.
+
+## 기본 출력
+
+핵심 문제 또는 지금 필요한 판단을 먼저 짧게 밝히고, 다음 표를 기본으로 정리한다.
+
+| 항목 | 내용 |
+|---|---|
+| **맥락** | 사용자가 하려는 일, 기대 결과, 현재 상태와 이 문제가 나온 배경 |
+| **문제점** | 확인된 문제·제약, 원인 또는 미확인 사항, 누구에게 어떤 영향이 있는지 |
+| **해결방안** | 실제 가능한 방안과 해결 원리, 변경 후 행동·결과, 장점·부담 |
+| **추천방안** | 추천안과 이유, 주요 단점, 필요한 다음 행동 |
+
+설계 선택이나 목표를 설명하는 경우에는 필요에 따라 **문제점**을 **검토사항**으로 바꾼다. 문제가 없거나 조치가 필요 없다면 억지로 해결책을 만들지 말고 그 사실과 이유를 설명한다.
+
+선택지 비교가 복잡하면 **해결방안을 별도 비교표로 분리**할 수 있다.
+
+직접 호출하지 않은 완료 보고는 **무엇이 달라졌는지 → 무엇을 실제로 확인했는지 → 남은 제한이나 필요한 행동**을 중심으로 전달한다. 해당하지 않는 항목은 생략한다.
+
+### 화면·동작의 전후 비교
+
+UI/UX 변경에서 배치·문구·동작의 차이를 말만으로 판단하기 어렵거나 사용자가 시각적인 비교를 요청하면, 변경 전후를 보여준다.
+
+텍스트 환경에서 화면 배치·컴포넌트 구성은 코드 블록 안의 ASCII/Unicode 선으로 **AS-IS → TO-BE** 와이어프레임을 보여주는 것을 기본으로 한다. 문구만 바뀌면 문구를 비교하고, 화면 이동이나 작업 절차가 바뀌면 전후 사용 흐름을 보여준다.
+
+이미 있는 화면·도식이나 다른 표현이 더 명확하면 활용한다. 도구 사용이나 새 산출물 제작은 요청 범위와 권한 안에서, 설명과 판단에 주는 이점이 추가 부담보다 클 때 선택한다.
+
+같은 사용자 과업·데이터·상황을 기준으로 비교하고, 변경을 이해하는 데 필요한 영역만 표현한다. 실제 또는 제안하는 버튼명·필드명·안내 문구를 넣어 사용자가 보게 될 내용을 알 수 있게 한다.
+
+상호작용이 있으면 행동 후 결과를 함께 보여준다. 처리 중·실패·복구·권한 제한 상태가 판단에 영향을 주면 필요한 범위만 포함한다. 문구가 약속하는 동작과 제안하는 기능이 일치하도록 한다.
+
+이미 확인한 화면·코드·사용자 설명을 활용하고, 확인된 현재 상태와 가정·제안을 구분한다. 현재 화면을 확인하지 못했다면 사용자 설명을 바탕으로 재구성했다고 밝히거나, AS-IS 미확인으로 표시하고 TO-BE만 보여준다. 신규 화면은 억지로 AS-IS를 만들지 않고 현재 사용 흐름이나 제안 화면을 보여준다.
+
+텍스트 도식은 읽기 쉽도록 **표 밖의 코드 블록**에 둔다. 표를 함께 사용하면 **해결방안**에는 변경의 요지와 이유를 적고, 실제 전후 차이는 도식이 설명하게 한다. 다른 항목도 도식에서 충분히 전달되었다면 요지만 남기거나 합쳐 반복을 줄인다.
+
+## 질문과 승인
+
+질문·승인 여부는 기존 프로젝트 정책과 사용자 위임 범위를 따른다. 그 안에서 사용자 결정이 필요한 미해결 사항만 질문한다.
+
+이미 위임받은 판단은 합리적인 방안을 선택해 처리하고 이유를 설명한다.
+
+질문이 필요하다면 단순히 "어떻게 할까요?"라고 묻지 말고 다음이 드러나게 한다.
+
+**무엇을 결정해야 하는지, 선택지의 차이가 무엇인지, 무엇을 추천하는지**
+
+설명이나 재정리 요청에 `진행할까요?` 같은 불필요한 실행 승인을 덧붙이지 않는다.
+
+## 품질 기준
+
+최종 답변만 읽어도 사용자가 현재 판단에 필요한 범위에서 다음 연결을 이해할 수 있어야 한다.
+
+**맥락 → 문제 또는 검토사항과 원인 → 선택지와 전후 차이 → 추천 이유와 필요한 행동**
+
+화면이나 동작을 바꾸는 설명은 사용자가 무엇을 보고, 무엇을 하면 어떤 결과가 나오는지 예상할 수 있어야 한다. 제안·미확인 사항이 이미 구현되거나 검증된 사실로 읽히지 않는지 확인한다.
+
+형식의 충족보다 사용자가 상황과 변경 결과를 이해하고 판단할 수 있는지로 완성도를 평가한다. 이해와 판단에 충분하면 설명을 마치고, 같은 내용을 도입·표·도식·결론에서 반복하지 않는다.