Agent 指南

本文件是 smartskill 项目的唯一 agent 指南。CLAUDE.md 保留为指向本文件的相对符号链接。

通用约定

其他项目可按需采纳本节，安装 Skill 不会自动写入这些约定。

• 优先级：在系统、开发者指令和工具权限边界内，当前任务的具体指令及已有授权优先，其次是适用的项目 AGENTS.md，最后是外部通用 Skill。Skill 中的建议不增加任务范围或审批步骤。
• 信息采纳：可以自主读取相关文件和上下文。采纳前判断来源、有效性、适用范围及用户当前意图，历史记录、草稿和既有实现不自动成为当前需求。能通过证据核实的先核实；仍无法判断信息是否可靠或用户是否希望引入时，说明来源、不确定点和影响，向用户确认后再推进依赖该信息的工作。其他不受影响的工作可以继续。
• 执行授权：审查、解释和诊断请求允许读取与分析；变更请求允许授权范围内的本地草稿、可恢复修改和常规测试。对外写入、发布、付费及不可逆或难回滚操作按实际授权处理；缺少必要授权时，先准备可审查的差异和方案，在实际操作前确认。已有明确授权不重复询问。
• 修改范围：保留用户未提交的修改，处理本次任务需要的文件和行为，不顺手重构、升级依赖或整理格式。遇到无法安全处理的重叠改动时说明具体阻塞。提交与安装遵循当前任务或项目约定，不因完成一步就自动执行。
• 检索与实现：从目标文件、相关模块和直接依赖开始；发现跨模块影响或证据不足时再扩大。实现满足当前需求的完整范围，优先采用已确认适用的现有能力，避免推测性功能与抽象。
• 验证：按行为变化与风险选择必要检查，完成项目必需检查。结果有效时不无故重复；后续代码、依赖或环境变化使结果失效时，重跑受影响项。普通测试在本地或隔离环境进行，按实际副作用判断授权，不以“测试”为由修改真实业务数据。
• 沟通与交付：默认中文，命令、路径和产品名保留原文。直接说明结论和必要依据，避免套话、重复总结及堆叠日志。进度只补充变化、发现或阻塞；交接时保留目标、已定决策、当前状态和未决问题。交付说明行为变化、验证结果与局限；值得理解的核心逻辑给位置和理由，后续会用到的接口或配置给必要契约。
• 文档：同一事实集中维护，其他位置引用。修改插在相关内容附近，保留任务以外的结构；代码、文档或历史决定不一致时先判断适用依据，不默认采用其中一方。事实和性能结论需有证据。
• Skill 加载：只使用匹配当前任务的入口及所需参考，不因引用了另一个主题就加载整套流程。需要暂停时说明具体动作、缺失信息或权限；若由 Skill 条款引起，引用准确文件和原句。

本仓库

• 项目结构、安装和四个 Skill 的入口见 README.md。
• 仓库内容与本机安装分开处理；修改本仓库不会自动更新已安装副本。
• 修改 Skill 后运行 python scripts/validate.py；修改校验器或安装器时运行对应的 scripts/test_validate.py、scripts/test_install.ps1 或 scripts/test_install.sh。