添加 AGENTS.md 记录项目协作原则与代码规范

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-04 10:50:32 +08:00
parent d9432bd529
commit 097853234f
1 changed files with 59 additions and 0 deletions
@@ -0,0 +1,59 @@
+# Karpathy原则
+
+## 先理解再修改
+
+- 检查实际实现、调用链和现有约束，不凭名称猜测行为。
+- 明确必要假设；遇到会显著改变结果的歧义时先说明。
+
+## 保持简单
+
+- 使用满足当前需求的最小方案。
+- 不增加推测性功能、无必要抽象或配置。
+
+## 精确修改
+
+- 只触碰与当前任务直接相关的代码，保留既有风格和无关改动。
+- 清理由本次修改产生的废弃代码，不顺便清理原有无关代码。
+
+## 面向验证
+
+- 修改前明确可观察的成功标准，修改后运行相关检查。
+- 如实报告警告、限制和未验证项。
+
+# MyParking项目规则
+
+## 代码边界
+
+- `CommonUsage-MultiVehicleSync`是独立的通用底盘库，不反向依赖`Shared`、M层或C层。
+- `Shared`只包含M/C共享的数据模型、数学方法和底盘适配代码。
+- `MedullaAdapter`负责M层硬件通信、IO和底盘命令。
+- `MultiWheelC`负责C层动作、控制、实验和数据记录。
+
+## 代码规范
+
+- 新增或修改的类、结构体和方法使用一句话的`/// <summary>`说明业务用途。
+- 单位、坐标系或正负方向不明确时补充说明，不复述代码字面内容。
+- Shared统一使用SI单位：m、m/s、rad、rad/s。
+- 车体坐标系为X向前、Y向左、逆时针为正；旧接口单位只在边界处转换。
+- 角度归一化、最短角差和度弧度转换统一使用`Shared/Mathematics/AngleMath.cs`，不重复手写。
+- 弧度归一化范围为`[-π, π)`，度归一化范围为`[-180°, 180°)`。
+- 车辆航向可用圆周最短角差；受`[-120°, 120°]`限制的机械舵角误差必须直接使用目标值减实际值。
+
+## 控制安全
+
+- 未经明确要求，不改变速度或舵角符号、CAN ID、遥控器映射、机械限位和模式切换策略。
+- 修改底盘命令、模式切换或四轮解算时，说明对实际运动的影响。
+- 实车测试采用低速、短距离，并确保可以立即停车。
+
+## 构建验证
+
+- 修改`CommonUsage-MultiVehicleSync`、`Shared`、`MedullaAdapter`或`MultiWheelC`后，在`MyParking`目录运行：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\build-and-package.ps1
+```
+
+- Release构建在命令末尾追加`-Configuration Release`。
+- 报告各项目的警告和错误，并确认M/C部署包使用同一份`CommonUsage.dll`。
+- 不直接编辑`bin`、`obj`、`build`和`output`中的产物。
+- 不手工覆盖`ref/CommonUsage.dll`，由构建脚本统一更新。