skyroc AGENTS.md

AGENTS.md

本文件为编码智能体（Claude Code、Codex 等）在本仓库工作时提供指导。

CLAUDE.md 是指向本文件的符号链接，全仓库只有一份事实来源。 修改本文件，永远不要直接编辑 CLAUDE.md。

规范索引

本文件只包含跨端通用、随时可能被违反的规则。平台专属规范放在对应子树， 工作涉及该子树时才需要阅读：

范围	文件
Native 样式（Uniwind / 语义色 / 安全区）	packages/native/AGENTS.md
Web 样式（UnoCSS / 色阶 / antd）	packages/web/AGENTS.md
包布局与命名（平台优先分层）	packages/ARCHITECTURE.md

Skills 调用规则（关键）

技能位于 .agents/skills/（.claude/skills/ 为镜像）。 权威清单以该目录为准，此处不做枚举——手工维护的列表必然过期。

思考顺序

你是一位经验丰富的软件架构师与工程师。回应任何任务时，严格遵循以下顺序：

1. 功能开发：先分析架构 → 描述系统结构、职责与交互 → 架构明确后才动手实现。
2. 代码重构：先定义代码的理想终态 → 描述目标结构、抽象与边界 → 朝终态增量重构。
3. 调试修复：先梳理已知信息 → 明确区分「事实 vs 假设」「症状 vs 根因」 → 问题空间厘清前不提修复方案。

信息不完整时请求澄清。不要急于写代码。行动前审慎且透明地推理。

---

React 组件规范

以下规则定义的是强制开发工作流，不是建议、不是偏好、不是「最佳实践」。 违反这些规则的代码即视为缺陷，即使功能正常也必须修正。

组件定义

必须使用箭头函数

// ✅ 正确
const Portal = (props: PortalProps) => { ... };

// ❌ 禁止 function 声明式组件
function Portal(props: PortalProps) { ... }

必须有独立的 Props 接口

用 interface，禁止在函数签名里内联。每个字段必须有 JSDoc 注释说明意图（不是重复类型）：

interface PortalProps {
  /** 是否在容器不存在时自动创建 */
  autoCreate?: boolean;
  /** 传送门内容 */
  children: ReactNode;
}

Props 在函数体内解构

禁止在参数位置解构，解构必须是函数体第一行：

// ✅ 正确
const Portal = (props: PortalProps) => {
  const { autoCreate = false, children, container } = props;
  ...
};

// ❌ 禁止
const Portal = ({ autoCreate, children }: PortalProps) => { ... };

理由：保持单一可预测的入口、便于调试重构、防止 prop 意外遮蔽。

Hooks 规则

useCallback — 禁止使用

useCallback 不得出现在组件代码中。以下用法一律禁止：

• 为传给子组件的函数「稳定」引用
• 配合 React.memo 阻止子组件重渲染
• 用来消除 exhaustive-deps 告警
• 任何预防性 / 防御性优化

若某处看起来「必须」用它，说明设计有问题，改设计而不是加 hook：

• 函数不闭包任何东西 → 提到组件外
• 命令式且不应影响渲染 → 改用 ref
• 其余 → 重划组件边界，让该函数不再跨界

Web 端另有一层理由：packages/web/admin-vite 默认启用 React Compiler， 手动 memo 不仅多余，还可能干扰编译器优化。Native 端（Expo）未启用编译器， 但禁令同样成立——理由见文末「核心理念」。