@uzysjung/agent-harness 26.184.0 → 26.186.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.js CHANGED
@@ -150,7 +150,7 @@ import {
150
150
  withoutAppleDouble,
151
151
  wrapHarnessBlock,
152
152
  writeInstallLog
153
- } from "./chunk-7ASVB2BV.js";
153
+ } from "./chunk-Q7JZK7RQ.js";
154
154
 
155
155
  // node_modules/sisteransi/src/index.js
156
156
  var require_src = __commonJS({
@@ -17,7 +17,7 @@ import {
17
17
  init_esm_shims,
18
18
  residentCost,
19
19
  resolveBundleRoot
20
- } from "./chunk-7ASVB2BV.js";
20
+ } from "./chunk-Q7JZK7RQ.js";
21
21
 
22
22
  // src/trust-tier-drift.ts
23
23
  init_esm_shims();
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@uzysjung/agent-harness",
3
- "version": "26.184.0",
3
+ "version": "26.186.0",
4
4
  "description": "Curate vetted AI-coding skills & plugins by your tech stack — install only what you need, across Claude Code, Codex, OpenCode & Antigravity",
5
5
  "type": "module",
6
6
  "publishConfig": {
@@ -12,7 +12,9 @@ and explicit authority take precedence over preferred methods.
12
12
  Start from the intended user's goal, the core usage flow, and what makes the
13
13
  outcome worth choosing over existing alternatives. Reuse relevant context and
14
14
  ground consequential decisions in project evidence or applicable authoritative
15
- sources. Make assumptions visible when they affect the result.
15
+ sources. Make assumptions visible when they affect the result. When an input
16
+ the task depends on is missing, report what is missing and what it blocks
17
+ instead of producing stand-in results that could pass for real ones.
16
18
 
17
19
  Define success by the outcome users need and the failures they must be protected
18
20
  from. Distinguish essential readiness from optional polish, using the intended
@@ -83,7 +85,10 @@ improvements and preferences separate. Once sufficient evidence supports the
83
85
  agreed readiness and applicable requirements, conclude rather than extend the
84
86
  work without a likely decision-changing benefit.
85
87
 
86
- Use unexpected results to update the diagnosis or approach. When no productive,
88
+ Use unexpected results to update the diagnosis before trying another fix; when
89
+ two fixes built on the same assumption have failed, test that assumption first.
90
+ Fix a fault where it first arises rather than where it surfaces; a guard is a fix
91
+ only when the state it handles can legitimately occur. When no productive,
87
92
  authorized path remains, report the precise blocker and what would resolve it.
88
93
  Report what changed, what is supported by evidence, and material remaining gaps.
89
94
 
@@ -34,10 +34,12 @@ context: fork
34
34
  | **MEDIUM** | 개선 기회 | 제안. 현재 PR에서 수정하지 않아도 됨 |
35
35
  | **LOW** | 스타일 · 선호 | 참고. 프로젝트 컨벤션 위반이 아니면 보고하지 않는다 |
36
36
 
37
- ### Step 4: Confidence Filtering
37
+ ### Step 4: Evidence Filtering
38
38
 
39
- - 확신 80% 이상인 이슈만 보고한다.
40
- - 변경되지 않은 코드의 이슈는 CRITICAL 보안 문제가 아니면 건너뛴다.
39
+ - 보고하는 이슈마다 어떻게 확인했는지 적는다 — **실행 · 재현**(실제 코드를 돌려 봤다) / **코드 경로 추적**(`file:line` 을 따라 실패가 닿는지 걸어 봤다) / **추론**(읽고 그럴 것이라 봤다). 싸게 할 수 있으면 실행 쪽으로 끌어올린다.
40
+ - 블로커는 추론만으로 세우지 않는다. 실행이나 경로 추적으로 확인하지 못한 위험은 미확인이라고 적고, 무엇을 돌리면 확정되는지 붙인다.
41
+ - 변경이 안전하다고 판정할 때도 그 판정을 떠받치는 사실과, 그것을 어디까지 확인했는지(위 세 단계 중 어디)를 적는다.
42
+ - 이번 변경과 무관한 기존 코드의 이슈는 CRITICAL 보안 문제가 아니면 건너뛴다. 다만 바뀌지 않은 코드라도 **이번 변경 때문에 깨지거나 새로 닿게 된 곳**(호출부 · 소비자 · 계약)은 이번 변경의 이슈다.
41
43
  - 유사한 이슈는 통합한다 ("5개 함수에서 에러 핸들링 누락" — 5건이 아닌 1건).
42
44
 
43
45
  ### Step 5: Output Format
@@ -57,6 +59,7 @@ context: fork
57
59
  [CRITICAL] Title
58
60
  File: path/to/file.ts:42
59
61
  Issue: 설명
62
+ Evidence: 실행·재현 | 경로 추적 | 추론 — 무엇으로 확인했나(미확인이면 확정할 실행)
60
63
  Fix: 해결 방향
61
64
 
62
65
  ### Positive Observations
@@ -0,0 +1,26 @@
1
+ SKILL.md in this directory is adapted from pstack benchmark-checklist
2
+ (https://github.com/cursor/plugins, https://github.com/michael-denyer/pstack-claude),
3
+ which is distributed under the following license.
4
+
5
+ MIT License
6
+
7
+ Copyright (c) 2026 Lauren Tan
8
+ Copyright (c) 2026 Michael Denyer
9
+
10
+ Permission is hereby granted, free of charge, to any person obtaining a copy
11
+ of this software and associated documentation files (the "Software"), to deal
12
+ in the Software without restriction, including without limitation the rights
13
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
14
+ copies of the Software, and to permit persons to whom the Software is
15
+ furnished to do so, subject to the following conditions:
16
+
17
+ The above copyright notice and this permission notice shall be included in all
18
+ copies or substantial portions of the Software.
19
+
20
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
23
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26
+ SOFTWARE.
@@ -0,0 +1,63 @@
1
+ ---
2
+ name: benchmark-checklist
3
+ description: >-
4
+ 성능 · 속도 숫자를 재거나 "빨라졌다 · 느려졌다 · 차이 없다"를 보고하기 전에, 그 숫자가
5
+ 기준선과 비교한 것인지 · 오류가 없었는지 · 일이 실제로 일어났는지 · 같은 조건인지 ·
6
+ 반복해도 나오는지를 실행 결과로 확인한다. 벤치마크를 돌릴 때, PR 에 전후 수치를 적을 때,
7
+ 성능 회귀를 주장할 때, 라이브러리 · 설정을 속도로 고를 때만 쓴다 — "N% 빨라졌다",
8
+ "벤치마크 돌려줘", "성능 비교", "속도 재 줘", "speedup", "benchmark", "perf regression".
9
+ 성능 주장이 없는 최적화 · 리팩터 · 테스트 작업에는 쓰지 않는다.
10
+ ---
11
+
12
+ # 측정 체크리스트
13
+
14
+ 성능 숫자를 만들었거나 그 숫자로 무언가를 주장 · 선택하려 할 때 쓴다 — PR 의 전후 비교, 회귀
15
+ 주장, 라이브러리 · 설정 선택. 아래 질문마다 코드를 읽고 한 추측이 아니라 **실행 결과**로 답한다.
16
+
17
+ 사용자가 대략적인 감만 원하면 한 번 실행으로 충분하다. 그때도 2번(오류)과 3번(실제로 일어났나)은
18
+ 확인하고, 한 번 잰 값이라고 밝힌다. 나머지는 그 결과가 이상해 보일 때만 본다. **여러 선택지 중
19
+ 하나를 고르는 일은 대략적인 감이 아니다.**
20
+
21
+ ## 재기 전에
22
+
23
+ - 내놓을 주장을 출하할 문장 그대로 먼저 적는다("60k 행 데이터에서 export p50 이 30% 빨라졌다").
24
+ 아래 질문은 그 문장을 시험한다.
25
+ - 측정 스크립트를 읽는다. 무엇을 재고, 무엇을 세고, 무엇을 빼는지 적어 둔다.
26
+ - 머신이 바쁜지 본다 — `uptime`, 코어 수(Linux `nproc` · macOS `sysctl -n hw.ncpu`). 바쁜데 멈출 수
27
+ 없으면 양쪽을 번갈아 돌려 같은 잡음을 받게 하고, 보고에 그렇게 적는다.
28
+
29
+ ## 질문
30
+
31
+ 1. **기준선을 잡았나?** 바꾸기 전 판을 같은 스크립트로 재서 숫자와 조건(커밋 · 데이터 크기 · 설정 ·
32
+ 머신)을 남긴다. 바꾼 뒤에 기억이나 예전 로그의 숫자와 비교하지 않는다.
33
+ 2. **오류가 났나?** 실패 · 비정상 응답 수를 세고, 출력이 있는지만이 아니라 맞는지 본다. 거절은
34
+ 대개 빠르고 타임아웃 · 재시도는 느리다 — 오류가 섞인 숫자는 어느 쪽으로든 틀린다. 스크립트가
35
+ 오류를 세지 않으면 세는 줄을 넣는다.
36
+ 3. **일이 실제로 일어났나?** 잰 구간 안에서 일이 돌았는지 확인한다 — 요청이 서버에 닿았고, 행이
37
+ 써졌고, 바이트를 읽었고, 코드가 그 결과를 썼다. 아무도 순회하지 않는 제너레이터, 아무도
38
+ 기다리지 않는 promise, JIT 가 버릴 수 있는 결과, 타임아웃은 일어나지 않은 일에 숫자를 만든다.
39
+ 계산으로도 본다 — 디스크 · 네트워크 대역폭이나 코어 수를 넘는 결과, 전체의 10% 를 쓰던 부분을
40
+ 없앴는데 11% 넘게 빨라진 결과는 일이 아니라 캐시 · no-op · 버그를 잰 것이다.
41
+ 4. **같은 조건인가?** 양쪽을 실제 운영처럼 돌린다 — 릴리스 빌드, 운영 플래그 · 환경 변수, 배치 ·
42
+ 트랜잭션 설정, 커넥션 풀, 운영과 같은 캐시 상태, 같은 버전과 데이터. 한쪽만 기본값이면 구현이
43
+ 아니라 설정을 비교한 것이다. 맞출 수 없으면 그 실행으로 승자를 고르지 않는다.
44
+ 5. **반복해도 나오나?** 양쪽을 최소 5번씩 번갈아(A, B, A, B …) 돌려 워밍업 · 지연 초기화 · 캐시 ·
45
+ 드리프트가 어느 쪽 편도 들지 않게 한다. 중앙값과 범위를 적는다. 실행마다 흔들리는 폭보다 작은
46
+ 차이는 **측정 가능한 차이 없음**이다.
47
+
48
+ ## 보고
49
+
50
+ - 판정부터 쓴다 — 빨라짐 · 느려짐 · 측정 가능한 차이 없음 · 판정 불가.
51
+ - 숫자는 단위 · 실행 횟수 · 범위 · 기준선과 함께 쓴다. 예: "p50 41 ms → 33 ms, 양쪽 7회 중앙값,
52
+ 변경 후 범위 32~35 ms, 기준선 = 변경 전 커밋, 같은 머신".
53
+ - 차이를 주장하는데 2번 · 3번을 확인하지 못했거나 한쪽만 조건이 달랐으면 **판정 불가**로 쓰고 빈
54
+ 곳을 밝힌다.
55
+ - 작은 부분의 결과는 사용자가 기다리는 전체 경로에서 차지하는 비중과 함께 적는다 — 요청 시간의 1%
56
+ 를 쓰는 함수는 아무리 빨라져도 요청을 1% 넘게 줄이지 못한다.
57
+
58
+ ## 출처
59
+
60
+ pstack 의 `benchmark-checklist`(Lauren Tan, cursor/plugins)를 Claude 판으로 옮긴
61
+ michael-denyer/pstack-claude 의 `plugins/pstack/skills/benchmark-checklist/SKILL.md`(커밋 `91ab921`)를
62
+ 줄여 한국어로 옮기고, 기준선 항목을 더했다. MIT License — 저작권 고지와 허가 문구 전문은 이
63
+ 디렉터리의 `LICENSE`.
@@ -66,11 +66,60 @@ design. The session integrates either result; neither arrangement requires an
66
66
  extra review by default. Compare separately developed alternatives when their
67
67
  different approaches justify the additional work.
68
68
 
69
+ Route by how open the work is. When what to do, or the answer itself, is still
70
+ open (setting direction, product planning, scoping, building a plan), use the
71
+ strongest reasoning model available. When a judgment stalls mid-task or a problem
72
+ needs a fresh angle, first measure what you can (run it, check the data, read the
73
+ code) and bring in the strongest model only if the judgment still splits. Design,
74
+ implementation, and verification inside a scope that a spec, the project's
75
+ direction, or a benchmark has already fixed go to a capable general model or the
76
+ session itself. Work with no judgment at all, such as link checks or confirming
77
+ that a rebased change matches the reviewed one, goes to tools, direct execution,
78
+ or the implementer.
79
+
80
+ Creative work with no single right answer (a name, a brand or product concept, a
81
+ visual direction, copy) gains more from breadth than from depth. Send the same
82
+ brief separately to two or three models with different tendencies and collect
83
+ their candidates. Leave your own examples and hypotheses out of that brief: one
84
+ example pulls every candidate toward it. Let the user choose from the candidates
85
+ side by side; simulated personas are not the user's judgment. Refining the chosen
86
+ direction is then work inside a settled scope.
87
+
69
88
  Choose effort by actual difficulty, interacting decisions, remaining uncertainty,
70
89
  likely rework, and the benefit of further reasoning. High stakes call for stronger
71
90
  assurance, not automatically maximum effort: inspecting code, contracts, tests,
72
91
  or external facts may resolve a risk that more reasoning alone cannot.
73
92
 
93
+ For open work, start at high effort. When open work is also hard to reverse
94
+ (permission boundaries, data deletion, migrations, money), start at a higher
95
+ effort; a high run followed by a rerun pays twice. Being hard to reverse alone
96
+ does not make work open: a migration whose answer is already settled goes to a
97
+ capable builder with a stronger reviewer, not to the strongest model. Count the
98
+ answer as settled only when a spec, a benchmark, or an established pattern
99
+ settles it, and send the work back up when the builder uncovers an open choice. Treat the maximum effort level as an
100
+ exception to raise with the user.
101
+
102
+ Judge every delegated result, from a planner, an implementer, or a reviewer, by
103
+ evidence rather than tone: a shallow report reads as confidently as a sound one.
104
+ An implementation or verification report needs the commands run with their exit
105
+ codes, and for a new guard, a record of the test failing when the guard is
106
+ reverted. A review of a consequential area (permissions, approvals, personal
107
+ data, exports, audit, migrations) needs a record of reverting the key lines and
108
+ watching the tests fail, the counterexample inputs actually run with their
109
+ results, and boundary-value checks; a claim of having tried a counterexample
110
+ without the input and the result counts as missing. A design or decision needs
111
+ the location of each current fact, what breaks if each option is wrong, the
112
+ conditions that would change the recommendation, and the assumptions it could
113
+ not confirm. A calculation needs its steps and raw data. Rerun only the part that
114
+ lacks this, with the doubt written into the request, instead of rerunning the
115
+ whole at a higher effort. When the doubt is about a calculation or a behavior,
116
+ measure it first and raise the effort only if the judgment still splits.
117
+ Narrow confirmation whose
118
+ answer is fixed (that a fix now passes the cited counterexample, that a document
119
+ points to the right decision, that issue or pull request status matches the
120
+ documents) needs only moderate effort, and moves up when it turns into finding
121
+ new counterexamples or making a judgment.
122
+
74
123
  ## 3. Make additional contexts earn their cost
75
124
 
76
125
  Add a worker for a concrete benefit: needed expertise or tools, useful context or
@@ -106,6 +155,24 @@ references, unresolved question, allowed changes, and completion criteria. Suppl
106
155
  enough context to decide correctly, including material failed approaches; favor
107
156
  accessible source references over replaying the conversation. Keep critical
108
157
  constraints explicit rather than relying on a lossy summary or hidden context.
158
+ A worker asked to plan or design from facts it cannot see will design from
159
+ assumption, so name where it can confirm the current facts (files, records,
160
+ queries) and give it read access to them. Where access itself would add a
161
+ boundary to check, such as production data, measure the few values it needs
162
+ yourself and pass them instead; when it cannot yet know which values it needs,
163
+ give read access to a copy or test environment rather than production.
164
+
165
+ How much to specify depends on how open the work is. For work whose scope is
166
+ already fixed, spell out the files, interfaces, expected values, and checks. For
167
+ open work handed to a stronger model, give direction instead of a procedure: the
168
+ background and context (who it is for, what has happened, the current facts and
169
+ where to confirm them), the goal to pursue and how the result will be judged, and
170
+ the guardrails (scope, constraints, budget, what must not happen, where to put
171
+ the result). Leave the decomposition to that model: which questions to ask, which
172
+ options to compare, and how to structure the answer. A list of sub-questions or a
173
+ prescribed outline fixes the shape of the answer before the stronger model has
174
+ looked at the problem. If you hold a hypothesis, pass it as one labelled input
175
+ the worker may reject.
109
176
 
110
177
  Ask for the result needed for integration, its evidence, and remaining gaps.
111
178
  Short results can return directly. Use durable files or artifacts for large,
@@ -155,7 +222,10 @@ context makes correction efficient; reassess only the affected evidence.
155
222
 
156
223
  Resolve model availability, effort controls, inheritance, and tool behavior from
157
224
  the actual environment or applicable documentation when needed; reuse current
158
- evidence. Distinguish requested settings from observed execution. Do not claim
225
+ evidence. Distinguish requested settings from observed execution: a requested effort or
226
+ model can be silently not applied. Where a per-call setting can be dropped, fix it
227
+ in the worker's definition, and still confirm the actual value from the
228
+ execution record before relying on it. Do not claim
159
229
  a model, effort level, or independent review that was not established.
160
230
 
161
231
  Apply the same scope, data protections, and approval boundaries to every worker,
@@ -110,7 +110,7 @@ peer collapses the panel toward one effective vote.
110
110
  exactly the long payload that gets dropped in transit, and the loss is silent. Losing one persona's
111
111
  report does not merely cost that report: it quietly shrinks the panel, which is the one variable
112
112
  the whole method depends on (see "Nine Judges, Two Effective Votes" above). Name the path when you
113
- spawn, not after — see [[model-orchestration]] "Worker lifecycle" for the general rule.
113
+ spawn, not after — see [[model-orchestration]] §4 "Transfer sufficient context, not entire histories" for the general rule.
114
114
 
115
115
  Prefer pinning the persona sub-agents to a cheaper tier (Sonnet) — see the cost-tier note. But this
116
116
  degrades gracefully: if the harness can't pin sub-agents to a specific model, just run the panel on
@@ -152,7 +152,7 @@ agent keeps its pane/window open and keeps pinging the session, and after two or
152
152
  clutter is the session. Read the persona's report file, then stop that agent in the same motion
153
153
  (TaskStop or the harness's stop mechanism); do not defer it to "cleanup later". By the time you
154
154
  start deduping, zero panel agents should still be running. The general rule and its rationale live
155
- in [[model-orchestration]] "Worker lifecycle" — this is that rule at panel scale.
155
+ in [[model-orchestration]] §6 "Preserve authority and continuity" — this is that rule at panel scale.
156
156
 
157
157
  Do **not** keep the panel alive for the step-6 second pass. Re-verification wants a *fresh* agent
158
158
  reading the fixed artifact from disk, not a resumed one carrying its own first-pass findings —
@@ -75,9 +75,9 @@ as a field that was considered and found empty, which is a claim you did not mak
75
75
  [검증 주체에 따라 하나 선택]
76
76
  - 자체 완결형: 별도 지시 없음. 검증 단계를 명시하지 않는다(모델 기본 동작에 맡김).
77
77
  단, success_criteria의 검증 명령이 있으면 그것으로 done을 판정한다.
78
- - 리뷰어 위임형: 테스트 작성·정합성 검증은 리뷰어 몫.
79
- 스스로를 통과시키는 검증 루프에 시간을 쓰지 말고, 동작 확인 수준의
80
- 스모크만 한 뒤 리뷰어가 판정 가능한 상태로 넘긴다.
78
+ - 리뷰어 위임형: 그 테스트가 충분한지 · 결과가 맞는지의 판정은 리뷰어 몫.
79
+ 완료 기준을 무는 테스트는 쓰되, 스스로를 통과시키는 검증 루프에 시간을
80
+ 쓰지 말고 리뷰어가 판정 가능한 상태로 넘긴다.
81
81
  인계 문서 [N줄] 이내: 임의로 정한 가정과 기본값 / 정답이 갈릴 수 있는 지점 /
82
82
  파라미터 위치 / 미심쩍은 부분 전부(심각도로 거르지 않는다, 판단은 리뷰어) /
83
83
  재현 시나리오(기대값은 적지 않는다).
@@ -87,9 +87,10 @@ await page.reload({ waitUntil: 'networkidle' });
87
87
 
88
88
  **두 가지 사용 형태**
89
89
 
90
- 0. **기존 launcher 를 먼저 정리한다** — `pkill -f "playwright|Chrome for Testing"`. 같은 profile
91
- dir 을 잡고 있는 창이 살아 있으면 `launchPersistentContext` 가 기동하지 못한다. 첫 실행은 되고
92
- **2회차부터** 실패하기 때문에 프로필 잠금이 아니라 스크립트 버그로 오진하기 쉽다.
90
+ 0. **같은 profile dir 을 쓰는 launcher 만 먼저 정리한다** — `pkill -f "<이 스크립트의 profile dir 절대 경로>"` 뒤
91
+ `pgrep -f` 같은 패턴이 비었는지 확인한다. 같은 profile dir 을 잡고 있는 창이 살아 있으면 `launchPersistentContext` 가
92
+ 기동하지 못한다 — 첫 실행은 되고 **2회차부터** 실패하기 때문에 프로필 잠금이 아니라 스크립트 버그로 오진하기 쉽다.
93
+ `playwright` · `Chrome for Testing` 처럼 넓게 잡으면 다른 세션의 브라우저 · Playwright MCP 서버까지 죽인다.
93
94
  1. **사용자가 직접 보는 경우** — `node scripts/<project>-launch.mjs` 를 포그라운드로 띄우고
94
95
  "URL / 로그인됨 / 직접 쓰세요"를 보고한 뒤, 추가 navigation·evaluate 를 **하지 않는다**.
95
96
  사용자 입력과 충돌한다.
@@ -192,7 +193,7 @@ L2/L3 fail이거나 차이가 임계 이상이면 에이전트가 다음 휴리
192
193
 
193
194
  - **REGRESSION 있음** → 수정 후 재실행 (Revision Gate)
194
195
  - **CHANGED만 있음** → 항목별 approve 또는 reject. approve 시 baseline 업데이트
195
- - **PASS만 있음** → 자동 baseline 업데이트 가능
196
+ - **PASS만 있음** → baseline 은 그대로 둔다(바뀐 것이 없다)
196
197
 
197
198
  ## Output
198
199
 
@@ -109,6 +109,25 @@ description: >-
109
109
 
110
110
  직접 호출하지 않은 완료 보고는 **무엇이 달라졌는지 → 무엇을 실제로 확인했는지 → 남은 제한이나 필요한 행동**을 중심으로 전달한다. 해당하지 않는 항목은 생략한다.
111
111
 
112
+ ### 표현 수단
113
+
114
+ 글과 표가 기본이다. 글로는 한 번에 들어오지 않는 내용이면 수단을 바꾼다.
115
+
116
+ - 구성 요소의 관계 · 흐름 · 순서 · 상태 변화는 도식으로 보여준다. 읽는 화면이 그려 주는 형식이 있으면 그것을, 없으면 코드 블록의 텍스트 도식을 쓴다.
117
+ - 항목이 많아 훑어보며 골라 읽어야 하거나 눌러 봐야 이해되는 내용은 한 파일로 열리는 HTML 페이지가 낫다. 쓰고 버리는 산출물이므로 미리보기 화면이나 프로젝트 소스 밖의 임시 위치에 두고, 무엇을 어디에 만들었는지 알린다.
118
+ - 영상은 사용자가 요청할 때, 설치된 영상 도구로 만든다.
119
+
120
+ 만드는 부담이 이해에 주는 이점보다 크면 글로 답하고, 더 나은 수단이 있어 보이면 한 줄로 제안한다.
121
+
122
+ ### 쉬운 문장
123
+
124
+ 처음 읽는 사람이 한 번에 따라오게 쓴다.
125
+
126
+ - 한 문장에는 한 가지만 말한다. 절차는 한 문장에 동작 하나다.
127
+ - 누가 무엇을 하는지 드러나게 쓴다.
128
+ - 한 개념에는 끝까지 한 용어를 쓰고, 처음 나올 때 뜻을 밝힌다.
129
+ - 일상어로 바꿀 수 있는 전문어 · 약어는 바꾸고, 꼭 필요한 것만 남긴다.
130
+
112
131
  ### 화면·동작의 전후 비교
113
132
 
114
133
  UI/UX 변경에서 배치·문구·동작의 차이를 말만으로 판단하기 어렵거나 사용자가 시각적인 비교를 요청하면, 변경 전후를 보여준다.