comet CLAUDE.md

回复语言

必须采用中文回答用户

测试

验证范围必须与改动风险相匹配，不要在每次编辑后默认运行全量测试。

• 每轮先运行覆盖当前改动的最小相关测试。
• 纯文档或 Skill 内容修改：运行相关契约测试和受影响文件的 Prettier 检查。
• 单一 app/、domains/ 或 platform/ 模块修改：运行对应测试；涉及编译、Runtime 或生成物时再运行 build。
• 跨模块、Runtime、安装/路由、发布准备或其他高风险修改：最终交付前运行一次全量测试。
• 全量测试失败或超时时，先定位原因；只有修正了明确原因后才重跑，不盲目重复。
• CI 已覆盖全量检查时，可以在本地只运行相关验证，但交付时必须明确说明未在本地运行的检查。

npx vitest run <相关测试文件>                     # 默认：最小相关测试
npx vitest run                                   # 高风险修改或最终交付前的全量测试

提交前检查

仓库已配置 Git pre-commit 钩子（husky + lint-staged），每次 git commit 会自动对 app/、domains/、platform/、scripts/、test/、.github/、config/ 下的暂存源文件运行 prettier --write（与 CI format:check 范围一致；冻结的 test/fixtures/ 除外），编辑器无关，所有贡献者生效。

根据改动范围选择提交前检查；不要求每个提交机械地运行全部命令（CI 会执行完整检查）：

pnpm format:check   # 大范围格式检查；小范围可只检查受影响文件
pnpm lint           # 修改源码、测试、脚本或配置时
pnpm build          # 涉及编译、Runtime、生成物或发布资产时
pnpm test           # 高风险修改或最终交付前需要本地全量验证时

注：本地 Windows 若 core.autocrlf=true，未改动的旧文件可能因 CRLF 被 prettier --check 误报；钩子只处理暂存文件，不受影响，旧文件下次编辑时会自动转为 LF。

Commit 规范

提交信息必须使用类型前缀，格式为 <type>: <summary>，scope 可选：<type>(<scope>): <summary>。

常用类型包括：feat、fix、docs、chore、refactor、test、build、ci、perf。

示例：

• feat: add eval report language switch
• fix(eval): prevent chart labels from overlapping
• docs: update contributor commit rules

项目结构规范

当前源码目录按责任分层：

• app/：CLI 入口、命令编排和用户交互层。只能组合 domain/platform 能力，不承载领域规则。
• domains/：业务领域模块。每个子目录是一个可独立维护的领域模块，例如 domains/bundle/、domains/comet-classic/、domains/comet-native/、domains/comet-entry/、domains/dashboard/、domains/skill/、domains/workflow-contract/。
• platform/：文件系统、进程、安装平台、版本、路径等平台适配能力。domain 不应直接散落平台差异逻辑。
• scripts/：构建、发布、benchmark、lint 等仓库自动化脚本。可调用源码模块，但不要成为运行时业务入口。
• assets/：发布资产和内置 Skill 内容。修改 runtime 源码后必须通过构建同步生成资产，不要把业务逻辑只写在生成物里。
• eval/scaffold/shell/ 中仅允许 config/repository-layout.json 明确列出的隔离评审 sidecar 入口；它们属于 Eval 容器边界，不是产品 Runtime 入口。

测试目录必须跟随被测对象归属：

• test/app/ 覆盖 app/ 命令和 CLI 行为。
• test/domains/<domain>/ 覆盖对应 domains/<domain>/ 模块；新增 domain 时同步新增同名测试目录。
• test/platform/ 覆盖 platform/ 适配层。
• test/scripts/ 覆盖 scripts/ 自动化脚本。
• test/repository/ 覆盖 README、CI、仓库布局等跨层约束。
• test/fixtures/ 和 test/helpers/ 只放测试数据与测试工具。
• 禁止新增或恢复 test/ts/ 这种横向桶；旧文件应迁移到上面对应目录。