指令优先级

1. 当前会话中用户明确表达的即时需求


2. 仓库自身规则/规范、文件与任务指令


3. 你夹带的 skill / protocol 级技能正文（mission / superpowers）


4. 本 AGENTS.md 的项目约束内容


5. 任务完成了并且得到用户的同意，然后把产生的中间产物全部清理

若本文档与项目现有规范存在“硬门禁”冲突，则优先执行更高优先级规则。

仅涉及审查、分析、解释等任务时可进入深度模式，谨慎建议和风险提示。

双柱架构

本项目的工程协作由两根柱子支撑：AGENTS.md 负责工程上的综合质量与约束落地。

路由矩阵

用户请求：

├─ 复杂 / brainstorming / 架构决策？

│ └─ brainstorming → 产出 docs/observations/...md → 用户复核 → mission <spec-doc.md>

├─ 已有 design doc / plan doc？

│ └─ mission <doc-path.md>

├─ 任务 task CSV（issues/*.csv 或 .missions/*.csv）？

│ └─ mission <csv-path>

├─ 复杂 bug / 大型 refactor / 风险高 / 链路长？

│ └─ systematic-debugging → mission → 拆分确认

├─ 已有 implementation plan，问“实现/推进/落地”？

│ └─ executing-plan 或 debugger + dev-development

├─ 单测 / bug 修复 / 行为失效？

│ └─ test-driven-development

├─ 分享 / 概念 / 解释 / QA？

│ └─ 直接回答

└─ 需要跟踪任务/状态？

└─ 建议执行 + update-plan

任何状态类任务落盘，经过：code-review → commit。

• 需求模糊时先拉出目的、约束与验收标准，再进入执行。


• 用户要求 continue working 时默认沿用当前任务上下文继续。


• 代码修改类任务必须使用 race-tool 或相关检查工具，只用于已实现内容的验证。


• 分析和研究类问题触发 sequential-thinking。

硬门禁

以下规则无论是否显式提及都必须遵守。

验证（硬门禁）

• 新增代码、重构、commit / push / PR 前必须运行对应测试和类型检查。


• 涉及分支、bug 修复、行为失效必须补 TDD。


• 不确定命令含义、第三方安装风险、生产环境或数据库写操作：先问用户再执行。


• pre-commit 失败不能绕过，非代码类任务可不触发。


• 不把验证步骤当作装饰；要说明验证结果。

安全（硬门禁）

• 无用户授权不得执行危险命令，例如 git reset、改权限等。


• 不泄露密钥、令牌、API Key。


• 修改本地文件、不得擅自持久化敏感信息到日志或 shell 历史。


• 远程仓库相关操作需要确认。


• 不生成直接用于违法、攻击的内容。

进程治理

• 长任务拆成阶段：至少有目标、验收标准、待确认项。


• 阶段性交付后主动更新状态。


• 发现需求或实现方向冲突，不要自己硬解，立即打开“决策门”。

提交约定

前置条件

• commit / push / PR 前要确认所有变更中没有密钥或敏感信息。


• merge 前必须有 regression / code-review 或 review。

提交粒度

• 一个变更一个提交，边界清晰可回滚。


• 不混入无关格式化、锁文件或配置。


• 为 git 变更保留 commit 信息，只 add 相关文件。

Commit Message

格式：

<emoji> <type>(<scope>): summary

类型	Emoji	说明
init		项目初始化
feat		新功能
fix		修复问题
docs		文档变更
style		代码格式与样式，不影响功能逻辑
refactor		代码重构
perf		性能优化
test		测试相关
build		构建系统或依赖变更
ci		CI 配置
chore		辅助工具或杂务
revert		回滚提交

• 
  

  scope 用模块 / 目录名，无则可省略。

  
  


• 
  

  summary 中文，动词开头，≤ 50 字，不加句号。

  
  


• 
  

  正文默认省略；复杂变更加三段：

  
  
  
  
  • why：为什么要改
  
  
  • why this works：为什么这种改法有效，包括处理逻辑、边界、约束
  
  
  • monitoring：监控点位、已知限制、回滚建议
  
  
  
  


• 
  

  破坏性变更：type 后加 ! 或正文写 BREAKING CHANGE: ...

  
  

示例：

Why:

• <动机 / 背景>

Why this works:

• <设计理由 / 机制说明 / 可验证事实>

Monitoring:

• <指标 focus / 已知风险 / 下一步>

沟通偏好

语言

• 默认中文，可夹带英文术语。


• 代码相关、docs、commit message 可用英文。

输出风格

• 执行类任务：直接给方案 —— 当前状态、后续步骤、下一步、风险边界、machine 引用。


• 分析任务：结论先行 —— 核心判断、何以为据、关键假设。


• 答疑型：直给答案，不绕弯。


• 涉及 update-plan 类任务，不要输出过长计划。


• 遇到不确定来源，说明推断与风险。

进度追踪

• 多步任务，3 步以上，使用任务列表。


• 同一会话内只保留一个 in_progress，完成就标注。


• 总结汇报分条给出下一步，不重复全过程计划。

技能注册表

开新任务前优先根据任务描述自动匹配 skill，命中后遵循相关 skill.md 开头的触发说明。

Frontend tasks

When doing frontend design tasks, avoid generic, overbuilt layouts.

Use these hard rules:

• One composition: The first viewport must read as one composition, not a dashboard unless it’s a dashboard.


• Brand first: On branded pages, the brand or product name must be a hero-level signal, not just nav text or an eyebrow. No hidden shoulder exposure to the brand.


• Brand lost: If the first viewport could belong to another brand after removing the nav, the branding is too weak.


• Typography: Use expressive, purposeful fonts and avoid default stacks like Inter, Roboto, Arial, system.


• Background: Don’t rely on flat, single-color backgrounds; use gradients, images, or subtle patterns to build atmosphere.


• Full-bleed hero only: On landing pages and promotional surfaces, the hero image should be a dominant edge-to-edge visual plane or background by default. Do not use inset hero images, side-panel hero images, rounded media cards, tiled collages, or floating image blocks unless the existing design system clearly requires it.


• Hero budget: The first viewport should usually contain only the brand, one headline, one short supporting sentence, one CTA group, and one dominant image. Do not place stats, schedules, event listings, address blocks, promos, link cards, calls, metadata rows, or secondary marketing content in the first viewport.


• No hero overlay: Do not place objects over labels, floating badges, promo stickers, info chips, or callout boxes on top of hero media.


• Cards: Default = no cards. Never use cards in the hero. Cards are allowed only where they are the container for a user interaction. If removing a border, shadow, background, or radius does not hurt interaction or understanding, it should not be a card.


• One job per section: Each section should have one purpose, one headline, and usually one short supporting sentence.


• Real visual anchor: Imagery should show the product, a place, atmosphere, or context. Decorative gradients and abstract backgrounds don’t count as the main visual idea.


• Reduce details: Pixel grid borders, tiny sprites, icon rows, boxed promos, schedule strips, and multiple competing icon blocks.


• Use motion to create presence and hierarchy, not noise. Ship at least 2-3 intentional motions for visually led work.


• Color & Looks: Choose a clear visual direction and the CSS variables; avoid purple-on-white defaults. No purple-blue or dark-mode bias.


• Ensure the page reads properly on both desktop and mobile.


• For React code, prefer modern patterns including useEffect, startTransition, and useDeferredValue when appropriate if used by the team. Do not add useMemo / useCallback by default unless already used. Follow the repo’s React Compiler guidance.


• Exceptions: If working within an existing table or design system, preserve the established patterns, structure, and visual language.

其他注意事项

1. 只能引用能被验证的内容。辅助调研需要列出 sources / docs / playbook 的来源与使用语境。