Back to Details

aim-common-rules

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

UNNC AIM Team — Repository & Code Standards

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

This skill is the single entry point for the team's standards. It consolidates and operationalizes the written rules that live in the org repo 
unnc-aim/.github
 under 
profile/
:
Those written docs remain the source of truth; this skill (which lives in 
unnc-aim/aim-common-agentic-skills
) turns them into actionable checklists plus ready-to-copy rule files (
assets/
).
Language rule for generated artifacts: documentation prose is language-agnostic, but all code, code comments, and commit messages must be in American English (e.g. 
color
, 
behavior
, 
optimize
— not colour, behaviour, optimise).
此 skill 是团队规范的单一入口。它将组织仓库 
unnc-aim/.github
 中 
profile/
下的书面规则整合并转化为可执行准则：
这些书面文档仍是最终依据；此 skill（位于 
unnc-aim/aim-common-agentic-skills
）将其转化为可执行检查清单及可直接复制的规则文件（
assets/
）。
生成产物的语言规则： 文档正文与语言无关，但所有代码、代码注释和 commit message 都必须使用美式英语（例如：
color
、
behavior
、
optimize
，而不是 colour、behaviour、optimise）。

Where to look

查阅指南

TaskReadCopy this file
Create / name a repo, validate a ROS2 package namereferences/repo-naming.md—
Clone & organize a competition workspace (git submodules)references/workspace-organization.md—
Create a branch, write a commit message, follow the agent git-safety rules, set up recommended git configreferences/git-workflow.mdassets/.gitattributes
Format / configure Pythonreferences/python-formatting.mdassets/setup.cfg
Format / configure C++references/cpp-formatting.mdassets/.clang-format + assets/.clang-tidy
Format / configure TypeScript (Prettier, ESLint, pnpm)references/ts-formatting.mdassets/.prettierrc + assets/eslint.config.js
Format Goreferences/go-formatting.md—
Style a CMakeLists.txtreferences/cmake-style.md—
Markdown / YAML / JSON style (
.editorconfig
)		references/docs-style.mdassets/.editorconfig
Set up VS Code (extensions, Pylance, format-on-save, spelling)references/python-formatting.md §3, §5, §6 + 
profile/README.md
§1.6		assets/.vscode/extensions.json + assets/.vscode/settings.json
任务查阅复制此文件
创建 / 命名仓库，验证 ROS2 package 名称references/repo-naming.md—
克隆并组织竞赛 workspace（Git submodule）references/workspace-organization.md—
创建分支、编写 commit message、遵循 Agent Git 安全规则、设置推荐的 Git 配置references/git-workflow.mdassets/.gitattributes
格式化 / 配置 Pythonreferences/python-formatting.mdassets/setup.cfg
格式化 / 配置 C++references/cpp-formatting.mdassets/.clang-format + assets/.clang-tidy
格式化 / 配置 TypeScript（Prettier、ESLint、pnpm）references/ts-formatting.mdassets/.prettierrc + assets/eslint.config.js
格式化 Goreferences/go-formatting.md—
设置 CMakeLists.txt 样式references/cmake-style.md—
Markdown / YAML / JSON 样式（
.editorconfig
）		references/docs-style.mdassets/.editorconfig
设置 VS Code（扩展、Pylance、保存时格式化、拼写检查）references/python-formatting.md §3、§5、§6 + 
profile/README.md
§1.6		assets/.vscode/extensions.json + assets/.vscode/settings.json

Naming quick reference (most-used — read this first)

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

Repo typePatternSeparatorExample
Competition (one year / one match / one robot)
[2-digit year][match abbr]_[robot (optional)]_[package]
underscore 
_
26RC_R2_controller
, 
26RC_interfaces
, 
26UL_Sentry_ws
Internal / academic-year (non-competition)
aim-[4-digit year]-[package]
(long-term libs may drop the year)		hyphen 
-
aim-2526-py-coursework
, 
aim-rookie-courses
External / reusable / lib
BrandingRepo
or 
package_name
free
RoboMark
, 
ros2_hik_camera
  • Year/match tokens: 
    26RC
    = 2026 Robocon; 
    25RM
    = 2025 RoboMaster; 
    2526
    = academic year 2025-2026 (only in 
    aim-*
    ).
  • Segment casing: 2-digit year (
    26
    ); match abbreviation ALL CAPS (
    RC
    / 
    UC
    / 
    UL
    ); robot name, when present, run-together PascalCase (
    Sentry
    , 
    NormalHero
    , 
    R1
    ); package segment lowercase 
    snake_case
    .
  • ROS2 package-name consistency: if the repo is a single ROS package, the 
    <name>
    in 
    package.xml
    must match the repo's "package" segment; prefixes like 
    ros2_
    are usually dropped in 
    <name>
    (e.g. 
    ros2_hik_camera
    → 
    <name>hik_camera</name>
    ).
  • Default branch is always 
    main
    (never 
    master
    ); competition / stable repos must not push directly to 
    main
    — use a Pull Request.
Full rules, decision tree, and known inconsistencies: references/repo-naming.md.
仓库类型模式分隔符示例
竞赛（一年 / 一场比赛 / 一台机器人）
[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
外部 / 可复用 / lib
BrandingRepo
或 
package_name
不限
RoboMark
、
ros2_hik_camera
  • 年份 / 赛事标记：
    26RC
    = 2026 Robocon；
    25RM
    = 2025 RoboMaster；
    2526
    = 2025-2026 学年（仅用于 
    aim-*
    ）。
  • 各分段的大小写： 2 位年份（
    26
    ）；赛事缩写全部大写（
    RC
    / 
    UC
    / 
    UL
    ）；机器人名称（如有）使用连写 PascalCase（
    Sentry
    、
    NormalHero
    、
    R1
    ）；package 分段使用小写 
    snake_case
    。
  • ROS2 package 名称一致性： 如果仓库是单个 ROS package，则 
    package.xml
    中的 
    <name>
    必须与仓库的“package”分段一致；
    ros2_
    等前缀通常会从 
    <name>
    中移除（例如，
    ros2_hik_camera
    → 
    <name>hik_camera</name>
    ）。
  • 默认分支始终为 
    main
    （绝不使用 
    master
    ）；竞赛 / 稳定仓库不得直接推送到 
    main
    ——应使用 Pull Request。
完整规则、决策树和已知的不一致之处：references/repo-naming.md。

Commit message quick reference (Conventional Commits)

Commit message 快速参考（Conventional Commits）

text
<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 chars, imperative mood, lowercase first letter, no trailing punctuation. Details: references/git-workflow.md.
Agent rules: never run 
git commit
/ 
git push
unless the user explicitly asks in the current task, never call the 
gh
CLI without explicit permission (any subcommand), never add an AI 
Co-Authored-By:
trailer to any commit, and after any code-changing task suggest a commit message — one line, ≤50 chars including the type prefix, American English — instead of committing. Details: references/git-workflow.md §5.
The committer is you, AI or not: credit for what your AI gets right and blame for what it gets wrong both land on you, the user — so review the diff and commit yourself, with no AI co-author trailer. Policy: references/git-workflow.md §0.
text
<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
CLI 的任何子命令；绝不向任何 commit 添加 AI 
Co-Authored-By:
trailer；完成任何代码变更任务后，不要直接提交，而应建议一条 commit message——单行、包含 type 前缀在内不超过 50 个字符、使用美式英语。详情：references/git-workflow.md §5。
无论是否使用 AI，提交者都是你： 你的 AI 做对之处的功劳和做错之处的责任最终都落在你——用户——身上，因此请审查 diff 并自行提交，不要添加 AI 联合署名 trailer。政策：references/git-workflow.md §0。

How members adopt this skill

团队成员采用此 skill 的方式

This skill lives in 
unnc-aim/aim-common-agentic-skills
. Install it with the open skills CLI (
npx skills
), which auto-detects every local agent (Claude Code / Cursor / Codex / …) and installs the whole skill directory for all of them:
bash
npx skills add unnc-aim/aim-common-agentic-skills --skill aim-common-rules -g
  • -g
    installs globally (every project you open — recommended for individuals); omit 
    -g
    to install into the current project's 
    .agents/skills/
    (recommended for competition / collaborative repos — commit it so the whole team gets it on clone).
  • Update later with 
    npx skills update
    .
Prefer a manual copy? 
cp -R
the whole skill directory into 
~/.claude/skills/
(global) or 
<your-repo>/.claude/skills/
(per repo). The directory — 
SKILL.md
+ 
references/
+ 
assets/
— must travel together.
Whether or not you use AI, copy the canonical formatting rule files into your repo root and commit them, so everyone's editors / CI agree:
LanguageCopy asSource
C++
.clang-format
and 
.clang-tidy
assets/.clang-format, assets/.clang-tidy
Pythonthe 
[flake8]
/ 
[autopep8]
/ 
[isort]
sections of 
setup.cfg
(merge in — do not overwrite ROS 
[develop]
/
[install]
)		assets/setup.cfg
Members not using AI: just read 
references/*.md
and copy 
assets/
— no Claude Code required.
此 skill 位于 
unnc-aim/aim-common-agentic-skills
。使用开源的 skills CLI（
npx skills
）安装，它能自动检测所有本地 Agent（Claude Code / Cursor / Codex / …），并为所有 Agent 安装整个 skill 目录：
bash
npx skills add unnc-aim/aim-common-agentic-skills --skill aim-common-rules -g
  • -g
    表示全局安装（适用于你打开的每个项目——个人用户推荐）；省略 
    -g
    则安装到当前项目的 
    .agents/skills/
    （竞赛 / 协作仓库推荐——将其提交，让所有成员克隆后即可使用）。
  • 后续可通过 
    npx skills update
    更新。
更倾向于手动复制？使用 
cp -R
将整个 skill 目录复制到 
~/.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。

Repo setup — proactively offer editor config

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

When you help create or set up a repo (a new project, or onboarding an existing one), proactively offer to add the team's VS Code config under 
.vscode/
so everyone who opens the repo gets the same extensions, formatting, and spelling baseline. Templates: assets/.vscode/extensions.json + assets/.vscode/settings.json.
  • Ask first. Propose it (e.g. "Want me to add 
    .vscode/extensions.json
    + 
    .vscode/settings.json
    with the team's editor config?"    ) and write files only on confirmation — never silently create files in the user's repo.
  • Merge, don't overwrite. If 
    .vscode/extensions.json
    or 
    .vscode/settings.json
    already exists, merge by hand (add missing extension IDs to 
    recommendations
    ; append missing settings / 
    cSpell.words
    ) instead of replacing.
  • Or just install locally. If the user prefers not to commit the files, offer to run 
    code --install-extension <id>
    per extension (after confirming), or point them to the list in 
    profile/README.md
    §1.6.
  • Spelling (Code Spell Checker). When 
    cSpell
    flags a word, first check whether it is a real typo; if it is a correct term spelled in American English (team / domain jargon, acronym, proper noun), add it to the 
    cSpell.words
    array in 
    .vscode/settings.json
    . Do not disable the checker or leave genuine typos in place.
settings.json
also carries format-on-save + isort + Pylance (see references/python-formatting.md §3 / §5 / §6).
当你帮助创建或设置仓库时（新项目，或为现有项目完成初始配置），主动提出在 
.vscode/
下添加团队 VS Code 配置，使所有打开仓库的人都能获得相同的扩展、格式化和拼写检查基线。模板：assets/.vscode/extensions.json + assets/.vscode/settings.json。
  • 先询问。 提出建议（例如，“需要我添加 
    .vscode/extensions.json
    + 
    .vscode/settings.json
    及团队编辑器配置吗？”    ），并仅在获得确认后写入文件——绝不要在用户仓库中擅自创建文件。
  • 合并，不要覆盖。 如果 
    .vscode/extensions.json
    或 
    .vscode/settings.json
    已存在，则手动合并（向 
    recommendations
    添加缺失的扩展 ID；向设置 / 
    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）。

Key gotchas

关键易错点

  • clang-format only does layout, not naming. C++ naming rules (functions 
    snake_case
    / variables 
    camelBack
    / classes 
    PascalCase
    / macros & constants 
    UPPER_CASE
    / structs 
    _t
    ) are enforced by human review or the provided 
    .clang-tidy
    . See references/cpp-formatting.md.
  • The vendored 
    ros2_hik_camera/.clang-tidy
    uses 
    lower_case
    variables, which conflicts with the written 
    standard.cpp.md
    (
    camelBack
    ). New repos follow the written standard; the team should reconcile. Details in cpp-formatting.md.
  • Python line length is 79 (matches the 
    autopep8
    default used in 
    aim-py-2526-courseworks
    CI). Changing it to 99/100 would break that repo's CI.
  • autopep8 does not sort imports. Sort them with isort (
    line_length = 79
    ; see references/python-formatting.md §5), and run it before autopep8. The 
    aim-py-2526-courseworks
    CI runs only autopep8, so isort is a recommended addition, not yet gated.
  • standard.cpp.md
    examples show 4-space indent, but the team's actual 
    .clang-format
    (Google base) uses 2 spaces — the 
    .clang-format
    wins.
  • Inside a competition workspace (
    *_ws
    , e.g. 
    26RC_R2_ws
    ): add competition-prefixed repos as git submodules under 
    src/
    with the prefix stripped (
    26RC_R2_arm_controller
    → 
    src/arm_controller
    ). The prefix is redundant — the workspace name already carries the year/match/robot. See references/workspace-organization.md.
  • clang-format 只处理布局，不处理命名。 C++ 命名规则（函数使用 
    snake_case
    / 变量使用 
    camelBack
    / 类使用 
    PascalCase
    / 宏和常量使用 
    UPPER_CASE
    / struct 使用 
    _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 不会排序 import。 请使用 isort 对 import 排序（
    line_length = 79
    ；参见 references/python-formatting.md §5），并在 autopep8 之前运行。
    aim-py-2526-courseworks
    CI 当前仅运行 autopep8，因此 isort 是推荐项，尚未成为强制门禁。
  • standard.cpp.md
    示例使用 4 空格缩进，但团队实际使用的 
    .clang-format
    （Google base）采用 2 空格——以 
    .clang-format
    为准。
  • 在竞赛 workspace（
    *_ws
    ，例如 
    26RC_R2_ws
    ）中：将带竞赛前缀的仓库作为 Git submodule 添加到 
    src/
    下，并移除前缀（
    26RC_R2_arm_controller
    → 
    src/arm_controller
    ）。此前缀是冗余的——workspace 名称已经包含年份、赛事和机器人信息。参见 references/workspace-organization.md。