@pzy560117/codex-harness 0.1.4 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/design/screen-states.md

@@ -0,0 +1,157 @@
+# Screen States 模板
+
+> 目标: 把每个页面状态写成可实现、可做 story、可做 visual regression 的状态规格。
+
+## 页面名称
+
+- Page ID:
+- 页面:
+- 路由/入口:
+- 角色:
+- 关联需求:
+- 关联设计稿:
+
+## 状态清单
+
+### default
+
+- 触发条件:
+- 数据条件:
+- 页面表现:
+- 用户可执行动作:
+- 组件影响:
+- story 名称:
+- visual baseline:
+
+### empty
+
+- 触发条件:
+- 数据条件:
+- 页面表现:
+- 用户可执行动作:
+- 恢复路径:
+- story 名称:
+- visual baseline:
+
+### loading
+
+- 触发条件:
+- 等待对象:
+- 页面表现:
+- 用户可执行动作:
+- 超时后行为:
+- story 名称:
+- visual baseline:
+
+### error
+
+- 触发条件:
+- 错误类型:
+- 页面表现:
+- 用户可执行动作:
+- 重试 / 兜底:
+- story 名称:
+- visual baseline:
+
+### submitting
+
+- 触发条件:
+- 提交对象:
+- 页面表现:
+- 用户可执行动作:
+- 防重复提交策略:
+- story 名称:
+- visual baseline:
+
+### retry
+
+- 触发条件:
+- 失败来源:
+- 页面表现:
+- 用户可执行动作:
+- 重试限制 / 节流:
+- story 名称:
+- visual baseline:
+
+### offline
+
+- 触发条件:
+- 网络条件:
+- 页面表现:
+- 用户可执行动作:
+- 恢复后行为:
+- story 名称:
+- visual baseline:
+
+### permission_denied
+
+- 触发条件:
+- 权限规则:
+- 页面表现:
+- 用户可执行动作:
+- 是否隐藏受限操作:
+- story 名称:
+- visual baseline:
+
+### disabled
+
+- 触发条件:
+- 禁用对象:
+- 禁用原因展示:
+- 用户可执行动作:
+- 恢复条件:
+- story 名称:
+- visual baseline:
+
+### long_content
+
+- 触发条件:
+- 极端数据:
+- 页面表现:
+- 用户可执行动作:
+- 截断 / 换行 / tooltip 规则:
+- story 名称:
+- visual baseline:
+
+### responsive/mobile
+
+- 触发条件:
+- 断点:
+- 页面表现:
+- 用户可执行动作:
+- 折叠策略:
+- 表格 / 列表替代形态:
+- 主操作可达性:
+- 触控目标:
+- 安全区策略:
+- 键盘遮挡处理:
+- 长文本 / 长标签处理:
+- story 名称:
+- visual baseline:
+
+### motion/reduced_motion
+
+- 触发条件:
+- 默认动效:
+- reduced motion 表现:
+- 用户可执行动作:
+- 组件影响:
+- story 名称:
+- visual baseline:
+
+## 状态到测试映射
+
+| 状态 | Story | Interaction Test | E2E | Visual |
+| --- | --- | --- | --- | --- |
+| default | | | | |
+| empty | | | | |
+| loading | | | | |
+| error | | | | |
+| submitting | | | | |
+| retry | | | | |
+| offline | | | | |
+| permission_denied | | | | |
+| disabled | | | | |
+| long_content | | | | |
+| mobile | | | | |
+| reduced_motion | | | | |

package/package-source/docs/codex-harness-engineering/templates/design/ui-image-review.md

@@ -0,0 +1,60 @@
+# UI Image Review 模板
+
+> 目标: 对 AI 生成的前端界面图进行评审。图片未通过前，不进入前端规范和代码实现。
+
+## 1. 评审对象
+
+| Image ID | Page ID | State | 图片路径 / 链接 | 版本 |
+| --- | --- | --- | --- | --- |
+| IMG-001 | page-001 | default | | v1 |
+
+## 2. 需求匹配检查
+
+| Requirement ID | 图片是否体现 | 证据 | 问题 | 结论 |
+| --- | --- | --- | --- | --- |
+| FR-001 | Yes / No / Partial | | | Pass / Fail |
+
+## 3. 状态覆盖检查
+
+| Page ID | State | 是否有图 | 是否符合 Screen States | 问题 | 结论 |
+| --- | --- | --- | --- | --- | --- |
+| page-001 | default | Yes | Yes / No | | Pass / Fail |
+
+## 4. 视觉与 CSS 规范检查
+
+| 检查项 | 预期 | 图片表现 | 结论 |
+| --- | --- | --- | --- |
+| 颜色 | | | Pass / Fail |
+| 字体 / 字号 | | | Pass / Fail |
+| 间距 | | | Pass / Fail |
+| 圆角 / 阴影 | | | Pass / Fail |
+| 信息密度 | | | Pass / Fail |
+| 响应式 | | | Pass / Fail |
+
+## 5. 交互与边界检查
+
+| 检查项 | 是否满足 | 问题 | 处理 |
+| --- | --- | --- | --- |
+| 主操作清晰 | Yes / No | | |
+| 空态可恢复 | Yes / No / N/A | | |
+| 错误态可重试 | Yes / No / N/A | | |
+| 权限差异清晰 | Yes / No / N/A | | |
+| 长文本不破版 | Yes / No / N/A | | |
+| 没有多余功能 | Yes / No | | |
+
+## 6. 评审结论
+
+- Verdict: PASS / FAIL
+- 必须重生成的图片:
+- 可通过编辑修复的图片:
+- 通过后进入: `image-to-frontend-spec.md`
+- 前端实现后还必须进入: `visual-parity-review.md`
+
+## 7. 通过标准
+
+- [ ] 每个 required state 都有图片或明确豁免。
+- [ ] 每个 P0/P1 需求都能在至少一张图中找到界面证据。
+- [ ] 图片没有添加需求之外的功能。
+- [ ] 图片符合 CSS / token / 组件规范。
+- [ ] 评审问题已关闭或转为新的图片编辑提示词。
+- [ ] 图片已作为后续浏览器截图对比的 reference source 记录保存路径。

package/package-source/docs/codex-harness-engineering/templates/design/visual-parity-review.md

@@ -0,0 +1,124 @@
+# Visual Parity Review 模板
+
+> 目标: 前端实现完成后，必须在真实浏览器中截图，并把实拍图与已评审通过的 UI 设计图对比。没有浏览器截图和图片对比证据，前端 UI 任务不能通过 Stage 1 Review。
+
+## 1. 评审对象
+
+| Feature ID | Page ID | State | Viewport | Route / URL | 设计参考图 | 浏览器实拍图 | 对比结论 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| | | default | Desktop 1440x900 | | `docs/design/assets/<feature>/<page>/default-desktop-reference.png` | `artifacts/visual-review/<feature>/<page>/default-desktop-actual.png` | PASS / FAIL |
+
+## 2. 前置条件
+
+- `ui-image-review.md` 对应图片已 PASS。
+- `image-to-frontend-spec.md` 已把设计图转成布局、组件、CSS/token、状态和数据规格。
+- 页面可以在真实浏览器打开。
+- 测试数据固定，避免商品名、价格、图片数量等动态内容导致误判。
+- 截图前关闭调试浮层、cookie 弹窗、浏览器扩展遮挡和非业务 toast。
+
+## 3. 产物目录规范
+
+```text
+docs/design/assets/<feature>/<page>/
+  <state>-<viewport>-reference.png
+
+artifacts/visual-review/<feature>/<page>/
+  <state>-<viewport>-actual.png
+  <state>-<viewport>-diff.png
+  <state>-<viewport>-review.md
+```
+
+说明:
+
+- `reference.png` 是评审通过的设计图或从设计稿导出的基准图。
+- `actual.png` 必须来自真实浏览器截图，不允许用设计图、静态 mock 图或裁剪后的局部图替代。
+- `diff.png` 可由视觉回归工具生成；如果没有像素 diff 工具，也必须生成 `review.md` 记录视觉模型或人工评审结论。
+- `artifacts/visual-review/` 可以进入 Git，也可以作为 CI artifact；如果不入 Git，trace / handoff 必须记录路径。
+
+## 4. 截图矩阵
+
+| Page ID | State | Viewport | 数据准备 | 参考图 | 实拍图 | 必须评审 |
+| --- | --- | --- | --- | --- | --- | --- |
+| | default | Desktop 1440x900 | | | | Yes |
+| | empty | Desktop 1440x900 | | | | Yes / N/A |
+| | loading | Desktop 1440x900 | | | | Yes / N/A |
+| | error | Desktop 1440x900 | | | | Yes / N/A |
+| | permission | Desktop 1440x900 | | | | Yes / N/A |
+| | long_content | Desktop 1440x900 | | | | Yes / N/A |
+| | default | Tablet 768x1024 | | | | Yes / N/A |
+| | default | Mobile 375x812 | | | | Yes / N/A |
+| | reduced_motion | Desktop 1440x900 | | | | Yes / N/A |
+
+## 5. 浏览器截图命令示例
+
+Playwright CLI 示例:
+
+```powershell
+New-Item -ItemType Directory -Force -Path .\artifacts\visual-review\pet-mall\home | Out-Null
+$env:VISUAL_BASE_URL = "http://localhost:5173"
+npx playwright screenshot --viewport-size=1440,900 "$env:VISUAL_BASE_URL/pets" ".\artifacts\visual-review\pet-mall\home\default-desktop-actual.png"
+```
+
+如果项目使用 browser / devtools 工具执行 E2E，也必须把截图保存到 `artifacts/visual-review/...`，并在报告中写明截图路径。
+
+## 6. 图片对比 Prompt
+
+把设计参考图和浏览器实拍图同时交给具备图片理解能力的 reviewer，使用以下提示词:
+
+```text
+请对比这两张图：
+1. 第一张是已评审通过的 UI 设计参考图。
+2. 第二张是真实浏览器截图。
+
+请只评审视觉还原，不重新设计页面。
+
+必须检查：
+- 页面结构、主次区域、导航、卡片、列表、表单和操作区是否一致。
+- 字体、字号、字重、行高、间距、圆角、阴影、边框、颜色是否明显偏离。
+- 商品图、图标、按钮、标签、价格、状态文本等业务元素是否缺失或多出。
+- 空态、加载态、错误态、移动端状态是否符合设计图和 screen-states。
+- 是否有文字溢出、遮挡、错位、重叠、响应式破版。
+- 动效、reduced motion、focus、hover、disabled 是否符合规格或有截图 / 录像证据。
+- 移动端触控目标、折叠策略、表格替代形态是否符合 screen-states 和 frontend architecture。
+
+输出：
+- Verdict: PASS / FAIL
+- 主要差异清单
+- 必须修复项
+- 可接受差异及原因
+```
+
+## 7. 对比记录
+
+| 检查项 | 参考图表现 | 实拍图表现 | 结论 | 修复任务 |
+| --- | --- | --- | --- | --- |
+| 布局结构 | | | PASS / FAIL | |
+| 字体与字号 | | | PASS / FAIL | |
+| 间距与密度 | | | PASS / FAIL | |
+| 颜色与状态色 | | | PASS / FAIL | |
+| 组件圆角 / 阴影 / 边框 | | | PASS / FAIL | |
+| 业务元素完整性 | | | PASS / FAIL | |
+| 响应式 | | | PASS / FAIL / N/A | |
+| 动效 / reduced motion | | | PASS / FAIL / N/A | |
+| 可访问性可见状态 | | | PASS / FAIL / N/A | |
+
+## 8. 失败处理
+
+如果 Verdict 为 FAIL:
+
+1. 把差异写入当前 task 的 `progress.txt` 或 worker `handoff.md`。
+2. 生成前端修复任务，明确允许修改的文件和必须重跑的截图矩阵。
+3. 修复后重新启动页面，重新截图。
+4. 用新的 `actual.png` 再次对比，直到 Verdict 为 PASS。
+5. 如果连续多轮仍无法一致，输出 `BLOCKED`，说明是设计图、规格、数据或技术约束冲突。
+
+## 9. 通过标准
+
+- [ ] 每个 required UI state 都有参考图或明确豁免。
+- [ ] 每个 required UI state 都有真实浏览器截图。
+- [ ] mobile required viewport 有真实浏览器截图或明确豁免。
+- [ ] 可访问性、focus、reduced motion 的可见状态已有截图、录像或报告证据。
+- [ ] 截图 viewport、测试数据和页面状态与参考图一致。
+- [ ] 图片对比报告存在，并给出 `Verdict: PASS`。
+- [ ] 所有 FAIL 差异都已修复并重新截图。
+- [ ] Stage 1 Review 能读取参考图路径、实拍图路径和对比报告。

package/package-source/docs/codex-harness-engineering/templates/docs/AGENTS.md

@@ -0,0 +1,19 @@
+# AGENTS.md
+
+## 目录作用
+
+- 存放会复制到项目 `docs/harness/` 的方法论文档模板和使用说明。
+
+## 结构索引
+
+- `harness-architecture.md`：分层架构。
+- `rule-governance.md`：规则治理。
+- `task-session-strategy.md`：会话与任务策略。
+- `new-project-usage.md`：新项目接入和使用。
+- `frontend-quality-rules.md` / `directory-structure-template.md` / `code-style-and-naming.md`：前端、目录、命名规则。
+- `service-dependency-matrix.md` / `architecture-constraints.md` / `env-and-deployment-template.md`：高风险 truth source 模板。
+
+## 修改规则
+
+- 这里放的是“安装后项目要读的深文档模板”，不是仓库根 README 的重复。
+- 如果规则已变成脚本 / lint / hook 可检查项，文档应解释用途和分层，而不是重复堆命令细节。

package/package-source/docs/codex-harness-engineering/templates/docs/architecture-constraints.md

@@ -0,0 +1,97 @@
+# Architecture Constraints Packet
+
+本文件在需求分析结束、进入计划或编码前完成。它把“系统应该是什么形态”转成可执行约束，供 `task.json`、Stage 1 Review 和验证命令使用。
+
+默认路径是 `docs/architecture/constraints.md`。项目可以在 `task.json.runtime.handoff.truth_sources.architecture` 中改用其他路径，但后续任务、prompt 和 review 必须读取同一组 truth source。
+
+## 1. System Shape
+
+- `delivery_shape`: `web_app` / `backend_service` / `monolith` / `frontend_app` / `cli` / `library` / `automation` / `data_pipeline` / `domain_prototype` / `other:<name>`
+- `runtime_model`: `http_service` / `worker` / `scheduled_job` / `static_site` / `embedded_library` / `command` / `not_applicable`
+- `deployment_unit`: `container` / `single_process` / `serverless` / `package` / `static_assets` / `not_applicable`
+- `production_entrypoints`: 列出当前项目真实启动入口、公开命令、页面入口、worker entry、package export、Dockerfile 或 `not_applicable`。
+
+## 2. Public Interface Boundary
+
+- `public_interfaces`: `HTTP` / `gRPC` / `GraphQL` / `MQ` / `CLI` / `UI route` / `package API` / `file format` / `none`
+- `contract_source`: `OpenAPI` / `protobuf` / `GraphQL schema` / `existing API` / `typed API` / `docs` / `not_applicable`
+- `interface_trace_rule`: 每个公开入口应能追踪到实现、测试和证据路径；没有公开入口时写明 `not_applicable`。
+
+## 2.1 Service And Contract Topology
+
+多服务、多仓库、契约或外部系统项目必须声明服务拓扑；不适用时写明 `service_matrix: not_applicable`。
+
+- `service_matrix`: `.service-matrix/dependencies.yaml` / `not_applicable` / `project_defined:<path>`
+- `affected_services`: 本轮需求会修改或影响的服务、应用、包、worker、前端入口或外部系统。
+- `upstream_downstream_rule`: 说明上游调用方和下游依赖方如何确认；不能只依赖代码搜索。
+- `contract_branch_rule`: IDL、OpenAPI、schema、generated code 或外部契约是否需要同分支、同版本或兼容性证明。
+- `change_gate_rule`: 对应 contract diff、consumer test、integration test、mock 更新、灰度或回滚检查。
+
+## 3. Data Boundary
+
+- `persistence_boundary`: `MySQL` / `PostgreSQL` / `SQLite` / `Redis` / `object_storage` / `filesystem` / `browser_storage` / `external API` / `none`
+- `schema_or_migration_required`: `yes` / `no` / `not_applicable`
+- `historical_data_strategy`: 旧数据如何兼容、回填、默认值和发布窗口；不适用写 `not_applicable`
+- `migration_rollback_strategy`: migration 如何回滚、降级或 feature flag 切换；不适用写 `not_applicable`
+- `repository_policy`: 说明声明交付路径使用的真实数据边界；测试替身、fixture、mock adapter 或 local-only adapter 只能用于声明允许的范围。
+- `consistency_requirements`: 事务、锁、幂等键、唯一约束、审计保留、缓存失效、离线同步或 `not_applicable`。
+
+## 4. Async And Worker Boundary
+
+- `async_required`: `yes` / `no`
+- `scheduling_model`: `DB polling` / `MQ consumer` / `cron` / `event bus` / `browser event` / `manual command` / `none`
+- `concurrency_control`: `DB row lock` / `optimistic CAS` / `distributed lock` / `single process` / `browser single-thread` / `none`
+- `time_source`: `database time` / `server time` / `event time` / `browser time` / `not_applicable`
+
+## 4.1 Backend Layering And Error Boundary
+
+如果项目包含后端服务、BFF、worker API 或命令式写路径，至少补齐：
+
+- `controller_policy`: Controller / Handler 只负责请求解析、权限入口、调用 service、响应映射；不堆业务规则。
+- `service_policy`: Service 负责业务逻辑、事务编排、幂等和副作用协调；不得直接依赖 `req/res/ctx/request/response`。
+- `repository_policy_detail`: Repository / DAO 负责数据库访问、查询组合和持久化边界；不返回页面展示字段。
+- `dto_policy`: DTO / Request / Response / Entity 的边界和禁止混用规则。
+- `error_handling_policy`: 全局异常处理、错误码模型、用户可见错误、日志保留策略。
+- `transaction_boundary`: 哪些写路径必须事务化，哪些步骤不得跨外部调用长持锁。
+- `idempotency_policy`: 哪些入口必须幂等，幂等键放在哪里，重复请求返回什么。
+
+## 5. Test Double Policy
+
+- `test_double_allowed_scope`: `unit_tests_only` / `contract_tests` / `local_demo` / `domain_prototype` / `not_allowed` / `project_defined:<rule>`
+- `mock_as_acceptance_evidence`: `no` by default；如果允许，必须写明原因、适用依赖、过期条件和替代真实验证计划。
+- `minimum_integration_evidence`: 列出当前项目最低真实验证组合，例如 UI + API、API + DB、CLI + filesystem、package API + consumer test、worker + queue，或 `not_applicable`。
+
+## 6. Forbidden Implementations
+
+按项目填充，不要只写抽象原则。示例只作为选项，不代表所有项目都适用：
+
+- 不允许只实现领域 service 而没有任务声明的公开入口。
+- 不允许公开契约有 operation 但代码没有对应实现或验证。
+- 不允许用测试替身、mock、fixture、local-only adapter 冒充声明交付路径。
+- 不允许把 `domain_prototype` 标记为可交付功能完成。
+- 不允许只运行 `git diff --check` 就声明 `feature_impl` 完成。
+
+## 7. Architecture Fitness Checks
+
+每个项目至少定义一个可运行或可审查的架构适配检查，并把命令或检查项同步到 `task.json` 的 `test_command`。
+
+```powershell
+<replace-with-project-fitness-check>
+```
+
+若暂时没有脚本，必须在 `docs/testing/verify-matrix.md` 写明等价检查项。可选检查包括：
+
+- 声明的生产入口存在，且能被启动、导入、访问或执行。
+- 公开接口与实现、测试和证据路径可追踪。
+- 声明交付路径未引用禁止的测试替身。
+- 需要持久化、worker、浏览器、文件或第三方服务时，存在对应的真实验证证据。
+- 不适用的边界已明确标记为 `not_applicable`，而不是留空。
+
+## 8. Definition Of Done
+
+- `architecture_constraints` 已从本文件或等价 truth source 复制到每个相关 `feature_impl` 任务。
+- 多服务、多仓库或契约任务已把服务矩阵、受影响服务和 change gates 复制到相关 `feature_impl` 的 `context_files`、`architecture_constraints`、`qa_contract` 和 `test_command`。
+- `forbidden_implementations` 已覆盖当前项目最容易跑偏的替代实现。
+- `test_command` 包含项目适配检查、affected tests、必要契约/集成/端到端验证和 `git diff --check`。
+- Stage 1 Review 对声明的架构形态给出 PASS。
+- 完成声明能说明声明交付路径、测试替身和不适用边界。

package/package-source/docs/codex-harness-engineering/templates/docs/code-semantics-and-navigation.md

@@ -0,0 +1,54 @@
+# 代码语义与导航层
+
+本文定义项目里的导航顺序，帮助 agent 先找到入口，再进入具体实现。
+
+## 默认顺序
+
+1. `docs/ai/repo-map.md`
+2. `docs/ai/architecture-brief.md`
+3. `docs/ai/CURRENT_TASK.md`
+4. 代码语义工具或全文搜索
+5. `docs/knowledge/*`
+
+## 职责边界
+
+- `docs/ai/*`: 文档导航层
+- 代码语义工具: 定义、引用、调用链、影响面
+- `docs/knowledge/*`: 历史经验和长期可复用知识
+
+## `docs/ai/*` 最低字段
+
+- `repo-map.md`
+  - 关键目录
+  - 阅读顺序
+  - 代码入口
+  - 调用链提示
+  - 测试入口
+  - 配置入口
+  - 禁改区
+- `CURRENT_TASK.md`
+  - 任务目标
+  - 验收标准
+  - owned paths
+  - 模块归属
+  - 类似实现
+  - 影响调用方
+  - 验证命令
+  - no-touch 区域
+- `API_MAP.md`
+  - 路由、命令、脚本或接口入口
+  - 配置接口
+  - 错误/认证入口
+- `DB_SCHEMA.md`
+  - 数据入口
+  - 关键实体
+  - 约束或持久化边界
+
+## 影响面分析最少回答
+
+- 入口在哪里
+- 上游是谁
+- 下游是谁
+- 受影响文件有哪些
+- 受影响测试和验证命令有哪些
+- 路由、权限、中间件、环境变量、build/deploy 是否会受影响

package/package-source/docs/codex-harness-engineering/templates/docs/code-style-and-naming.md

@@ -0,0 +1,116 @@
+# 项目级命名词典与边界模板
+
+这份文档不是固定规则入口。固定不变的第五章规则已经放进 always-on 的 `coding-style.md`。
+
+这里专门承载项目特有、会随业务变化的内容：
+
+- 业务词典
+- 历史别名兼容
+- 某些目录的命名例外
+- 类型后缀禁用表和替代方案
+- 当前项目的文件命名分层表
+
+## 1. 适用原则
+
+- 先读规则文件 `coding-style.md`，这里不重复抄固定规则。
+- 这里的每一项都应当是“当前项目特有事实”，不是通用工程常识。
+- 如果某项约束对所有项目都成立，应上收回规则文件，而不是继续堆在本文。
+
+## 2. 业务词典
+
+先维护“一个概念一个名字”的项目词典。
+
+| 业务概念 | 统一名称 | 禁止混用的别名 | 说明 |
+| --- | --- | --- | --- |
+| 用户 | `user` | `member`、`customer`、`client` | 如果确实是不同角色，拆成独立概念 |
+| 商品 | `product` | `goods`、`item`、`commodity` | 只保留业务正式名词 |
+| 订单 | `order` | `bill`、`trade` | 支付单可单独定义 `paymentOrder` |
+| 优惠券 | `coupon` | `voucher`、`ticket` | 如果有券模板，再单独定义 `couponTemplate` |
+
+补齐项目自己的业务词典时，至少回答：
+
+- 这个概念在页面、接口、数据库、测试里是否同名。
+- 是否已经存在历史别名；如果有，兼容层放在哪里。
+- 新增同义词时，是新概念还是旧概念的脏别名。
+
+## 3. 项目文件命名分层表
+
+先按目录层级声明规则，再允许新增文件。
+
+| 路径 / 资产类型 | 命名规则 | 示例 | 禁止情况 |
+| --- | --- | --- | --- |
+| React / Vue 页面组件 | `PascalCase` | `UserProfilePage.tsx` | 与同层 `user-profile-page.tsx` 混用 |
+| 通用 hooks | `camelCase` 且以 `use` 开头 | `useUserProfile.ts` | `userHook.ts`、`getUserHook.ts` |
+| 纯工具函数 | `camelCase` | `formatPrice.ts` | `dealData.ts`、`tool.ts` |
+| 测试文件 | 跟随被测对象 + `.test` / `.spec` | `formatPrice.test.ts` | `test1.ts` |
+| 文档模板 | `kebab-case` | `code-style-and-naming.md` | `codeStyle.md`、`code_style.md` |
+
+新增文件前必须回答：
+
+- 这个文件属于页面、feature、shared、contract、testing 还是 scripts。
+- 同目录现有文件使用什么规则。
+- 如果要破例，为什么不能沿用当前目录规则。
+
+## 4. 项目特有命名例外
+
+这里只记录项目例外，不重复写通用函数命名原则。
+
+- 哪些历史目录仍在使用旧命名风格：
+- 哪些生成代码目录允许例外：
+- 哪些第三方契约文件不按项目规则命名：
+- 哪些 legacy 字段名必须保留原样：
+
+## 5. 类型命名边界
+
+同一个项目里，`Entity`、`DTO`、`Response`、`FormValues`、`ViewModel` 这些后缀必须先定义边界。
+
+| 类型后缀 | 用途 | 不该承载什么 |
+| --- | --- | --- |
+| `Entity` | 持久化模型 / 数据库实体 | 前端展示字段 |
+| `Dto` / `DTO` | 服务边界输入输出 | ORM 细节、UI 状态 |
+| `Response` | API 返回结构 | 表单临时状态 |
+| `Request` | API 请求参数 | 数据库存储字段 |
+| `FormValues` | 表单输入态 | 服务端完整实体 |
+| `ViewModel` | 页面展示聚合模型 | 持久化约束 |
+
+如果项目不使用这些后缀中的某些项，要在这里明确写：
+
+- 禁止使用哪些后缀。
+- 统一替代方案是什么。
+- 历史遗留命名如何兼容。
+
+## 6. 新增命名前必须确认
+
+实现前先确认这 5 件事：
+
+1. 这个名词是否已在业务词典中定义。
+2. 同类文件在当前目录如何命名。
+3. 这个函数名是否表达了主动作和对象。
+4. 这个类型属于哪一层边界，是否需要后缀。
+5. 是否会和历史别名、旧接口字段或数据库字段冲突。
+
+## 7. 自动化与人工门禁
+
+建议自动化命令：
+
+```text
+lint
+typecheck
+format
+test
+git diff --check
+```
+
+Harness 侧至少保留两层约束：
+
+- `coding-style.md` 默认自动加载固定规则。
+- `CURRENT_TASK.md` 和本文记录当前项目 / 当前任务的特有词典与边界。
+- `style-lint.ps1` 同时检查规则文件和项目级模板是否完整。
+
+## 8. 评审检查单
+
+- 同一业务概念是否出现多个别名。
+- 同层文件是否混用了多套命名风格。
+- 新函数名是否仍然依赖 `do/process/check` 这类模糊词。
+- `User`、`UserInfo`、`UserData`、`UserModel` 之类类型是否有明确边界。
+- 新增字段、接口、测试数据、文档是否与统一名词同步。