Imported from xuthus5/mssh (
AGENTS.md). Install upstream withnpx skills add xuthus5/mssh. Copyright stays with the author.
项目约定
前端设计风格
- 整个前端项目使用 shadcn/ui 设计风格（React）
- 使用 CSS 变量令牌：
bg-background、text-foreground、text-muted-foreground、border-border等 - 使用 shadcn/ui 风格的组件：Button、Input、Card、Switch 等
- 所有页面保持 shadcn/ui 的
rounded-xl、shadow-sm、border风格
项目要求
- 所有方法与函数要有完备的测试用例覆盖，要求代码行覆盖率达到>=90%
- 代码中的错误都需要处理，这里的处理意思是当有返回错误的时候需要用变量接受，当确定错误无关紧要，也要使用 _ 来忽略，而不是完全忽略
- 代码编写完毕后需要使用golangci-lint和goimports-reviser进行格式化与lint处理
- 杜绝在for循环中使用defer
- 对已有功能流程的任何修改（包括交互逻辑、API 签名、架构方案变更）必须征得用户明确同意后方可实施，禁止擅自变更
- 编写代码需要注意安全性，创建的目录权限为0700，创建文件的权限为0600，如果确定需要给予可执行权限的时候才能给文件0700权限
- 执行测试过程中产生的临时构建产物，比如二进制文件，测试数据等要进行清理
- 代码编写完毕后，如果项目有README.md文件，需要做必要的修改，注意确保README.md文件的简洁性，不要啰嗦
- 提交 / 推送前必须跑通与 CI 对齐的本地门禁：
wails3 task ci（或wails3 task check）。该命令依次执行：golangci-lint run --timeout 5m ./...（与 CI 同命令；工具版本与 CI 保持一致，当前为 v2.12.2）- 后端：
go test -race -coverprofile=coverage.out -covermode=atomic -coverpkg=./internal/...,./pkg/... ./internal/... ./pkg/...，且 total coverage ≥ 90% - 前端：
npm run check:source-limits、npm run check:bundle-budget、npm test（在frontend/） - 生产构建：
wails3 task build（等同 CI 的生产构建） 任一步失败严禁提交或推送。仅跑部分测试/构建不算完成门禁。
Agent 规则
本文件用于约束自动化代理在本机工作区中的默认工作方式，并将 grill-me 作为需求澄清与方案校验工作流。
指令优先级
- 当前会话中用户的明确要求
- 仓库自身规则、文档与约定
- 本
AGENTS.md - 相关
grill-me/ skill 流程定义
- 项目禁止使用 Superpowers 工作流及其相关技能。
- 需要需求澄清、方案评审或复杂设计时，使用
grill-me工作流替代 Superpowers。 - 本文件保留个人硬门禁、环境约束、交付偏好与沟通方式。
- 只读分析任务可不进入完整实现流程，但结论必须清晰、可追溯。
- 若用户明确要求
continue nonstop，默认持续推进，直到满足验收标准或出现真实阻塞。
默认原则
最短路径与并行轻重分流
- 默认采用"满足质量要求的最短路径"。
- 默认先判断任务是否适合并行；适合则优先并行，不适合再串行。
- 能直接完成并验证的，不升级为更重流程。
- 能用轻量 planning 解决的小任务，不升级为重文档流程。
- 能用单一专项 skill 解决的问题，不额外扩展工作流。
轻量任务默认策略（Claude / grill-me）
- 轻量任务：单文件或小范围修改、明确 bug 修复、配置 / 文案调整、小测试补充、局部文档修改。
- 轻量任务可跳过完整方案访谈与重 review 链，直接实现并做定向验证；中大型任务必须先使用
grill-me；仅在关键不确定且无法从当前对话、项目上下文、AGENTS.md、现有代码回答时才提问。 - 提问：轻量任务首次最多问 1 个关键问题；中任务优先一次性给出 2 到 3 个方案与推荐；已有上下文可回答的信息不重复提问；若未获回复且风险可控，应说明假设后继续推进。
- 文档：design / spec / plan 默认仅服务执行；仅在用户明确要求、项目规范要求或确有长期协作价值时入库；轻量任务不强制生成独立 spec / plan 文件。
- 默认授权边界：当前分支内可默认修改与任务直接相关的应用代码、测试、局部文档，并新增少量配套文件。
- 以下操作仍必须确认：删除文件、大规模重构、shared contract / schema / shared types、根配置 / CI / 依赖 / 环境模板、数据库 / 持久化变更、git 历史与远程操作、基础设施或越界改动。
- 平台偏好：复杂任务优先在当前分支使用
grill-me；仅独立任务才并行处理，并避免非必要的工作树隔离。 - 总原则：小任务走轻量路径；中大型任务先使用
grill-me澄清和校验，再进入实现与验证。
流程升级 / 降级
- 升级到更重流程：影响边界超出初始判断、涉及公共 API / schema / 持久化 / 并发 / 共享逻辑、需求仍不清晰、验证覆盖不足、任务演变为中大型实现或重构。
- 降级到更轻流程：改动局部且边界清晰、不涉及共享核心逻辑、验证直接、补长计划或补测试的成本明显高于收益、问题已收敛为单点修复。
任务分流模型
只读任务
- 分析、解释、架构说明、代码阅读、纯信息型问答及其他不改文件的只读审查，可直接处理。
- 真实问题排查但尚未进入修改时，优先使用结构化调试方法。
实现任务与质量门禁
- 适用：新功能、bug 修复、行为变更、重构，以及页面 / 组件 / API / 脚本 / 数据处理逻辑改动。
- 默认流程：
grill-me -> implementation；轻量任务至少明确：目标、边界、风险、验证方式。 - 完成前进行常规代码审查与最终验证；前端任务使用
frontend-design。
推进与验证
Step by Step Reasoning Workflow
- 需求模糊时，先澄清目标、约束、验收标准与边界条件。
- 多步任务维护可见任务列表；任一时刻仅保留一个
in_progress。 - 回答时优先给结论，再补背景、依据与权衡。
- 遇到新信息应主动修正之前的判断。
- 多步任务优先使用
update_plan维护高层进度。
Environment
- 环境初始化优先遵循仓库文档与项目级 AGENTS。
- 若无明确要求，仅做当前任务所需的最小准备。
Command Verification Rules
- 不得虚构已运行命令、退出码或验证结果。
- 关键验证无法执行时，必须明确说明原因。
- 没有验证证据，不得声称"通过""完成""可提交""可合并"。
Change Delivery Gate
在声明完成、准备 commit、准备 push、准备发起 PR 之前，应满足：
- 已完成与本次改动直接相关的验证，并如实报告结果
- 已完成对应质量门禁；提交/推送前默认执行
wails3 task ci（与.github/workflows/ci.yml对齐） - 若仓库要求更重验证，优先遵循仓库规则
- 若关键验证无法执行，明确说明原因，并降低完成度表述
实现任务后处理
- 代码实现完成并通过本地质量门禁后，默认直接执行
git commit与git push，无需等待用户再次提醒。 - 若本地质量门禁失败、远端推送被拒绝、涉及 destructive action、历史重写、force push 或无法确认变更范围，应停止并向用户报告原因。
- commit 前必须复查
git status、git diff --check与本次变更范围，避免提交临时产物、代理/换源配置或无关文件。
Commit 规范
- 格式：
<type>(scope): <summary> scope可选summary使用英文、动词开头（祈使句）、首字母小写、长度 ≤ 50 字符、不加句号- 常用
type：feat/fix/refactor/docs/test/chore
测试策略与质量门禁
- TDD 不对所有实现类任务默认强制；是否启用按"行为影响、共享范围、回归风险、测试价值"显式判定。
- Level 0：定向验证——局部、低风险、小改动
- Level 1：回归测试——中小修复或局部行为变化
- Level 2：TDD——新功能、明确行为变更、共享逻辑或高风险改动
- Level 3：Code Review——遵循上文 Review 规则
- Level 4：Completion Verification——遵循上文完成前验证与 Change Delivery Gate
工程实践
快速上手
- 阅读仓库上下文：相关文件、文档、最近提交，优先理解模块边界
- 若用户提供
plan2go=<path>，将该文件视为当前执行来源并保持同步 - 需要理解架构、调用链、数据流、入口与依赖关系时：
- 优先使用
mcp__ace-tool__search_context rg/grep只用于已知字符串的精确定位- 若用户要求"找出所有出现位置"，可先用 ace-tool 缩小范围，再用
rg枚举；架构结论以 ace-tool 为准
- 优先使用
文档维护
- 计划、目标、约束、关键决策、经验教训、步骤或进度变化时，应同步更新相关文档。
- 默认文档根目录：
./docs。 - 默认按"当前仓库所在文件夹层级"在该根目录下建立子目录后再落文档。
- 对反复证明有价值的经验，应沉淀到项目级
AGENTS.md。 - 经验模板最小包含：标题、触发信号、根因 / 约束、正确做法、验证方式、适用范围。
执行原则
- 先澄清，再实现；先缩小边界，再扩展范围。
- 优先局部修改与最小充分实现，避免无关扩张。
- 若复杂度上升，及时升级流程，而不是硬撑轻流程。
- 若任务已收敛为局部改动，及时降级流程。
Bug / Test / Code / Refactor
- Bug 报告应写清现象、触发条件、预期、实际、影响范围、严重程度及日志 / 堆栈 / 环境信息；真实 bug 默认优先结构化调试，先确认根因再修复。
- 测试优先覆盖关键路径、边界情况和错误路径；断言优先 expected 在前、actual 在后。
- 编码遵循 SOLID、DRY、关注点分离、YAGNI；命名清晰，边界条件显式处理。
- 代码硬性上限：函数 ≤ 50 行、文件 ≤ 300 行、嵌套 ≤ 3、位置参数 ≤ 3、圈复杂度 ≤ 10、禁止魔法数字。
- 重构默认先保持行为不变，再提升结构质量；必要时先补测试再重构；若出现循环导入则提取共享逻辑；较大重构先拆分计划，完成后仍回到 review 与 completion verification。
Safety Rules
- 不要运行破坏性命令（如
git reset），除非用户明确要求。 - 不要使用非 Git 工具操作
.git。 - 避免危险删除命令，除非范围明确限制在临时产物。
- 不要将密钥、凭证、API Key 硬编码进源码。
- 数据库访问使用参数化查询。
- 不要用不可信输入拼接 shell 命令或 SQL。
- 除非用户明确要求，否则不要终止非当前任务启动的进程。
沟通与输出
沟通风格
- 默认使用简体中文回答，可混用英文技术术语。
- 代码标识符使用英文。
- 代码注释优先简体中文，保持简洁清晰。
混合输出模式
根据任务类型选择合适的输出风格：
- 执行类任务：强调进度、当前动作、下一步
- 分析类任务：强调结论、依据、权衡
模式 A：执行进度式
适用场景：代码修改、重构、bug 修复、多步任务、文件操作
推荐结构：
🎯 任务：一句话描述当前任务
📋 执行计划：
- ✅ 已完成
- 🔄 进行中
- ⏸ 待执行
🛠️ 当前进度： 详细描述当前正在做什么，已完成什么
⚠️ 风险/阻塞： 潜在问题、注意点、阻塞因素
📎 参考：file:line
模式 B：分析回答式
适用场景：问答、代码解释、方案对比、架构分析、问题诊断
推荐结构：
✅ 结论：1-2 句直接回答核心问题
🧠 关键分析：
- 核心观点
- 依据
- 权衡
🔍 深入剖析：（可选） 📊 方案对比：（可选） 🛠️ 实施建议：（可选） ⚠️ 风险与权衡：（可选）
技术内容规范
- 多行代码、配置、日志优先使用带语言标识的 Markdown 代码块。
- 示例聚焦核心逻辑，省略无关部分。
- 需要强调差异时，可使用
+ / -。 - 仅在确有必要时使用表格。
输出结尾建议
- 复杂内容后附简短总结，重申核心要点；结尾给出实用建议、行动指南或鼓励进一步提问。
收尾整合
- 所有子任务完成后必须统一收尾，不得默认认为"子任务完成 = 项目完成"。
- 收尾至少包括：汇总改动、检查冲突面、分析依赖与建议合并顺序、必要时新增 integration task、补整合性修复、运行最终验证（test / lint / build / smoke）、输出最终 merge plan。
技能（Skills）
- 技能存放位置：
~/.claude/skills/（个人）与.claude/skills/（项目共享，可选）。 - 开始任务前，应优先判断是否命中对应 skill；命中时阅读
SKILL.md并按流程执行。 - 本文件默认采用以下主干整合方式：
- 实现前：复杂任务使用
grill-me - debug：结构化调试
- review：常规代码审查
- 完成前：最终验证
- 高风险行为变更：先编写回归测试
- 前端设计：
frontend-design
- 实现前：复杂任务使用
- 本地个人工作流 skill 可保留私人默认路径、私人笔记目录与本机脚本入口；若对外发布，必须基于单独副本做脱敏，不直接公开
~/.claude/skills/源文件。 - 调研总结 / 输出笔记：
research-note-wrap - 会话收尾：
session-wrap - 提交总结 / 日报：
commit-daily-summary - 项目级日报：
project-daily-summary - 分支 / 并行任务收口：完成最终差异检查与验证
- 在回复中声明本次使用了哪些技能。