dsh-engineering

1# 应用和维护 DSH 工程规范
2 
3先读[项目上下文](references/project-context.md)和[验证证据](references/evidence.md)。按用户任务选择下面的流程。普通开发使用“用于日常开发”；接入或迁移项目规范需要对应的任务要求。
4 
5## 用于日常开发
6 
71. 阅读受影响的代码、实际调用方和项目必需检查。先明确要实现的行为，再选择抽象或调整约定。
82. 涉及实现或设计选择时，读[编码规范](references/code-conventions.md)；涉及行为变化时，读[测试选择](references/test-strategy.md)。按当前任务检查默认值、输入校验、依赖方向、扩展点和测试覆盖，不顺带清理无关代码。
93. 用户要求实现时完成实现；要求设计或审查时给出具体方案或结论。验证相应真实入口和必需检查，区分已执行与建议执行的检查。已安装且与任务有关时，使用专门的审查、错误处理、UI 或性能 Skill；本 Skill 自带所需的基础规则。
104. 必要时更新现有行为文档。不要仅因开发一个功能或修复一个问题，就创建接入记录、新的 Agent 指令或工程手册。完成时说明行为变化、实际证据和重要限制。
11 
12## 修改规范前先诊断
13 
141. 明确请求属于诊断、接入、更新还是撤销。诊断保持只读。
152. 检查适用指令、目录、清单、真实检查命令、CI 和现有文档的维护位置，识别已有优势和具体缺口。
163. 新项目只记录已知事实和用户选定的技术栈，不虚构测试命令。已有项目复用原有文档，保留更严格的政策。优先解决当前问题，不套用通用目录模板。
174. 简短列出“缺口 → 涉及的现有文档 → 具体补充”。用户已经要求实现或接入时，在该范围内继续执行。
18 
19## 接入项目
20 
211. 选择尽量少的文档，通常是现有 Agent 指令入口和开发指南。阅读[文档写作](references/prose.md)；只有确需新建负责维护这些内容的文档时，才使用[项目指南模板](templates/project-guide.md)。不要留下占位内容。
222. 找到当前安装的 Skill 目录。编辑前运行自带的[接入工具](scripts/adoption.py)：
23   `python3 <skill-dir>/scripts/adoption.py snapshot --project <root> --paths AGENTS.md <other-docs> --output <new-temporary-snapshot.json>`。
24   只指定明确的 UTF-8 文档，不采集凭据、无关文档或整个目录。临时快照保持私有，放在版本管理范围之外。
253. 只修改任务涉及的文档，补足项目导航、职责归属、真实开发和检查命令、证据标准与文档维护规则。保留本地约定，不放宽检查或安装新依赖。阅读[编码规范](references/code-conventions.md)和[测试选择](references/test-strategy.md)，根据项目实际风险选取规则。补充通往已安装 Skill 或现有规范的简短日常入口，不整份复制参考库。
264. 对照清单和 CI 核实命令，对照真实路径检查链接。项目要求时执行必需检查。新增可执行规则时，必须用真实错误样例证明检查会拒绝违规情况。
275. 从 [UPSTREAM.json](UPSTREAM.json) 读取版本和固定上游提交 SHA，再运行：
28…