aim-common-rules

UNNC AIM 团队 — 仓库与代码规范

此技能是团队规范的唯一入口。它整合并落实了组织仓库 unnc-aim/.github 中 profile/ 下的书面规则：

• 仓库命名 / 分支 / 提交规则 ← profile/README.md
• C++ 规范 ← profile/standard.cpp.md
• Python 规范 ← profile/standard.py.md
• TypeScript / Go / CMake 规范 ← profile/standard.ts.md / standard.go.md / standard.cmake.md
• 文档风格（Markdown / YAML / JSON）← profile/standard.docs.md

这些书面文档仍是权威来源；此技能（位于 unnc-aim/aim-common-agentic-skills）将它们转化为可执行的检查清单和可直接复制的规则文件（assets/）。

生成制品的语言规则：文档正文不限定语言，但所有代码、代码注释和提交消息都必须使用美式英语（例如 color、behavior、optimize，而非 colour、behaviour、optimise）。

查阅指南

任务	阅读	复制此文件
创建 / 命名仓库，验证 ROS2 包名称	references/repo-naming.md	—
克隆并组织竞赛 工作区（git 子模块）	references/workspace-organization.md	—
创建分支、编写提交消息、遵守 Agent 的 git 安全规则、设置推荐的 git 配置	references/git-workflow.md	assets/.gitattributes
格式化 / 配置 Python	references/python-formatting.md	assets/setup.cfg
格式化 / 配置 C++	references/cpp-formatting.md	assets/.clang-format + assets/.clang-tidy
格式化 / 配置 TypeScript（Prettier、ESLint、pnpm）	references/ts-formatting.md	assets/.prettierrc + assets/eslint.config.js
格式化 Go	references/go-formatting.md	—
编写 CMakeLists.txt 样式规范	references/cmake-style.md	—
Markdown / YAML / JSON 样式（.editorconfig）	references/docs-style.md	assets/.editorconfig
设置 VS Code（扩展、Pylance、保存时格式化、拼写检查）	references/python-formatting.md §3、§5、§6 + profile/README.md §1.6	assets/.vscode/extensions.json + assets/.vscode/settings.json

命名快速参考（最常用 — 请先阅读）

仓库类型	模式	分隔符	示例
竞赛（一个年份 / 一场比赛 / 一台机器人）	[2-digit year][match abbr]_[robot (optional)]_[package]	下划线 _	26RC_R2_controller、26RC_interfaces、26UL_Sentry_ws
内部 / 学年项目（非竞赛）	aim-[4-digit year]-[package]（长期维护的库可以省略年份）	连字符 -	aim-2526-py-coursework、aim-rookie-courses
外部 / 可复用 / 库	BrandingRepo 或 package_name	不限	RoboMark、ros2_hik_camera

• 年份 / 比赛标记：26RC = 2026 年 Robocon；25RM = 2025 年 RoboMaster；2526 = 2025-2026 学年（仅用于 aim-*）。
• 分段大小写： 两位年份（26）；比赛缩写全大写（RC / UC / UL）；机器人名称（如有）采用连写 PascalCase（Sentry、NormalHero、R1）；包名段采用小写 snake_case。
• ROS2 包名一致性： 如果仓库是单个 ROS 包，package.xml 中的 <name> 必须与仓库的「包名」段一致；ros2_ 之类的前缀通常会在 <name> 中省略（例如 ros2_hik_camera → <name>hik_camera</name>）。
• 默认分支始终为 main（绝不能使用 master）；竞赛 / 稳定版仓库不得直接推送到 main — 应使用 Pull Request。

完整规则、决策树和已知的不一致之处：references/repo-naming.md。

提交消息快速参考（Conventional Commits）

<type>(<scope>): <subject>
<blank line>
<body>           # optional, wrap at <=72 chars
<blank line>
<footer>         # optional: BREAKING CHANGE: ... / Closes #123

type ∈ feat | fix | docs | style | refactor | test | chore | perf | ci | build；subject ≤ 50 个字符，使用祈使语气，首字母小写，末尾不加标点。详情请参阅：references/git-workflow.md。

Agent 规则： 除非用户在当前任务中明确要求，否则绝不运行 git commit / git push；未经明确许可，绝不运行会产生写入效果的 gh 命令（只读子命令，如 gh pr view / gh run list，不受此限制）；绝不在任何提交中添加 AI 的 Co-Authored-By: trailer；完成任何会更改代码的任务后，应建议一条提交消息，而不是执行提交——单行，含类型前缀不超过 50 个字符，使用美式英语。详情请参阅 references/git-workflow.md §5。

提交者就是你，无论你是不是 AI： 你的 AI 做对了什么，功劳归你；做错了什么，责任也由你承担。因此请检查差异并亲自提交，不要添加 AI 联合作者 trailer。政策：references/git-workflow.md §0。

成员如何采用此技能

此技能位于 unnc-aim/aim-common-agentic-skills。使用开源的 skills CLI（npx skills）安装。它会自动检测每个本地 Agent（Claude Code / Cursor / Codex / …），并为所有 Agent 安装整个技能目录：

npx skills add unnc-aim/aim-common-agentic-skills --skill aim-common-rules -g

• -g 表示全局安装（适用于你打开的每个项目——推荐个人使用）；省略 -g 则安装到当前项目的 .agents/skills/ 中（推荐用于竞赛 / 协作仓库——请将其提交，以便整个团队克隆仓库时都能获取）。
• 之后可使用 npx skills update 更新。

更喜欢手动复制？使用 cp -R 将整个技能目录复制到 ~/.claude/skills/（全局）或 <your-repo>/.claude/skills/（每个仓库）。目录中的 SKILL.md、references/ 和 assets/ 必须一起迁移。

无论你是否使用 AI，都请将规范的格式规则文件复制到仓库根目录并提交，以确保所有人的编辑器 / CI 采用一致的配置：

语言	复制为	来源
C++	.clang-format 和 .clang-tidy	assets/.clang-format、assets/.clang-tidy
Python	setup.cfg 中的 [flake8] / [autopep8] / [isort] 部分（合并进去——不要覆盖 ROS [develop] / [install]）	assets/setup.cfg

不使用 AI 的成员：只需阅读 references/*.md 并复制 assets/——无需 Claude Code。

仓库设置——主动提供编辑器配置

协助创建或设置仓库（新项目，或为现有项目配置新成员）时，请主动提供将团队的 VS Code 配置添加到 .vscode/，这样每个打开仓库的人都能获得一致的扩展、格式设置和拼写检查基线。模板：assets/.vscode/extensions.json + assets/.vscode/settings.json。

• 先询问。 提出建议（例如 “要我添加包含团队编辑器配置的 .vscode/extensions.json + .vscode/settings.json 吗？”），只有在得到确认后才写入文件——绝不要在用户的仓库中擅自创建文件。
• 合并，不要覆盖。 如果 .vscode/extensions.json 或 .vscode/settings.json 已存在，请手动合并（将缺少的扩展 ID 添加到 recommendations；补充缺少的设置 / cSpell.words），而不是直接替换。
• 或者只在本地安装。 如果用户不想提交这些文件，可提出按扩展逐个运行 code --install-extension <id>（确认后），或指引他们查看 profile/README.md §1.6 中的列表。
• 拼写（Code Spell Checker）。 当 cSpell 标记某个单词时，先检查它是否确实拼错。如果该词是拼写正确的美式英语（团队 / 领域术语、首字母缩略词、专有名词），请将其添加到 .vscode/settings.json 中的 cSpell.words 数组。不要禁用检查器，也不要放任真正的拼写错误。

settings.json 还包含保存时自动格式化 + isort + Pylance（参见 references/python-formatting.md §3 / §5 / §6）。

关键注意事项

• clang-format 只负责排版，不负责命名。 C++ 命名规则（函数使用 snake_case / 变量使用 camelBack / 类使用 PascalCase / 宏和常量使用 UPPER_CASE / 结构体使用 _t）由人工审查或提供的 .clang-tidy 强制执行。请参阅 references/cpp-formatting.md。
• 随附的 ros2_hik_camera/.clang-tidy 使用 lower_case 变量命名，这与书面标准 standard.cpp.md（camelBack）冲突。新仓库遵循书面标准；团队应协调统一。详情请参阅 cpp-formatting.md。
• Python 行长度为 79（与 aim-py-2526-courseworks CI 使用的 autopep8 默认值一致）。改为 99/100 会导致该仓库的 CI 失败。
• autopep8 不会排序导入项。 请使用 isort 排序（line_length = 79；参阅 references/python-formatting.md §5），并在运行 autopep8 之前运行它。aim-py-2526-courseworks CI 只运行 autopep8，因此建议添加 isort，但目前尚未将其纳入门禁。
• standard.cpp.md 中的示例使用 4 个空格缩进，但团队实际使用的 .clang-format（以 Google 为基础）采用 2 个空格——应以 .clang-format 为准。
• 在竞赛工作区内（*_ws，例如 26RC_R2_ws）：将带竞赛前缀的仓库作为 Git 子模块添加到 src/ 下，并去掉前缀（26RC_R2_arm_controller → src/arm_controller）。前缀是多余的——工作区名称已经包含年份、比赛和机器人信息。请参阅 references/workspace-organization.md。