- 每个函数、类和模块都应只有一个明确的修改原因。
- 避免处理多重关注点的“上帝函数”。
- 如果你在描述一个函数时使用了“和”，它很可能违反了单一职责原则。
- 倾向于使用组合，而不是庞大的多用途单元。
- 倾向于可读的代码，而不是“自作聪明”的抽象。
- 避免过早优化。
- 如果初级工程师无法在30秒内理解 → 请简化。
- 让依赖关系可见。
- 避免隐藏的状态变化。
- 避免“魔法行为”（隐式全局变量、副作用）。
- 尽可能隔离 I/O、网络和文件系统操作。
将逻辑划分为清晰的层级：
- UI / 接口层
- 业务逻辑层
- 数据 / 持久层
- 工具 / 助手（纯函数） 智能体规则： 除非有明确理由，否则绝不要将数据访问与业务逻辑混合。
- 倾向于模块化的文件，而不是大型单体文件。
- 保持合理的文件大小（软规则：<300–500行）。
- 按功能分组，而不是按类型分组（通常更适合系统扩展）。
- 除非规模需要，否则优先选择模块化单体架构，而不是微服务。
- 优先使用 SASS： 使用 SASS (
.scss) 进行样式设计，而不是标准 CSS 或内联样式。 - 使用
_projects： 利用_projects/目录中的模块化项目自动注册系统来创建新项目。 - 系统扩展： 在现有系统内工作并在需要时进行扩展，而不是创建全新的并行架构。
- 日历页面约定：
navigation/calendar.md里的布局和弹层样式要放到 SCSS 中，用语义化 class 代替 utility 风格的内联类。 - 跨域 API： 供
pages.opencodingsociety.com调用的 Spring API 端点要显式允许带凭据的跨域请求。 - 文档： 必要时为困难或复杂的实现创建详细文档。
- 注释： 为非平凡的逻辑添加注释，但要保持简短，重点关注“为什么”而不是“是什么”。
- 提问： 如果系统级约束、需求或模式不清楚，请在继续之前暂停并向用户提问。
- 以 Makefile 为唯一指令来源；常用目标
make/make serve-current、make dev、make stop、make convert、make convert-single（细节见 README.md）。 - 顺序很关键：stop → build projects → convert notebooks/docx → split courses → jekyll serve（以 Makefile 为准）。
- 源文件在 notebook sources 与 docx sources；转换后的 Markdown 输出到 generated posts（生成物，不要手工改）。
- 多课程拆分文件（
*_csp.md/*_csa.md/*_csse.md/*_content.md）为生成物，禁止手改；规则见 scripts/split_multi_course_files.py。 - Notebook/DOCX 转换规则见 scripts/convert_notebooks.py 与 scripts/convert_docx.py。
- 新项目遵循 _projects/REGISTRATION.md 注册/构建约定；架构示例见 _projects/ARCHITECTURE.md。
- 样式优先使用 SCSS；主题切换与样式约定见 README.md。
- 后端服务位于 node_backend/README.md，与站点构建流程分离；改动前先阅读该文档。
命名应：
- 解释意图，而不是实现。
- 避免使用缩写，除非是标准缩写。
- 在整个代码库中保持一致。
- 示例：使用
normalizeUserTransactionData()而不是procData2()。
- 快速失败： 尽早验证输入，立即抛出包含清晰信息的错误，不要默默忽略失败。
- 防御性编程： 假设输入无效或恶意，为边缘情况添加保护，绝不信任外部数据源。
- 纪律： 绝不默默吞没异常。在错误中始终包含上下文，并在适当的地方使用类型化/自定义错误。
- 记录有意义的事件，而不是噪音。
- 日志应回答：发生了什么以及为什么？
- 避免记录敏感数据。
- 测试应描述行为，而不是实现。
- 每条关键逻辑路径都应可测试。
- 逻辑优先使用单元测试，流程优先使用集成测试。
- 智能体规则： 如果代码改变了行为，请更新或添加测试。
- 确保确定性行为（除非明确需要，否则避免随机性，需要时固定种子）。
- 对于非平凡任务：在编码前写一个简短计划。
- 在实现前将其分解为多个步骤。
- 除非必要，否则优先考虑最小的差异，而不是重构。
- 无故不要重写正在工作的代码。
- 匹配现有代码库的风格和结构。
- 除非必要，不要引入新架构。
- 验证假设： 如果不清楚，请谨慎推断并标记假设。绝不默默猜测关键需求。
- 同步更新文档： 随着你在迭代中犯错、学习新的系统模式或约束，主动用重要的注意事项更新
AGENTS.md，并确保同步更新AGENTS_MD_DOCUMENTATION.md（英文说明版本），以便系统随时间不断改进。
- 避免做太多事情的函数。坚持单一职责原则。
- 通过保持明确且记录良好的副作用来确保可预测性。
- 你需要它吗 (YAGNI)： 除非现在需要，否则不要构建功能。避免推测性的泛化。
- 仅在保证正确性后才进行优化（优化前进行性能分析）。