Imported from YimingYin1213/team-pages (
AGENTS.md). Install upstream withnpx skills add YimingYin1213/team-pages. Copyright stays with the author.
智能体编程指南
核心原则
单一职责原则
- 每个函数、类和模块都应只有一个明确的修改原因。
- 避免处理多重关注点的“上帝函数”。
- 如果你在描述一个函数时使用了“和”，它很可能违反了单一职责原则。
- 倾向于使用组合，而不是庞大的多用途单元。
简单胜于精巧
- 倾向于可读的代码，而不是“自作聪明”的抽象。
- 避免过早优化。
- 如果初级工程师无法在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 为准）。
- 项目构建后必须运行 SASS 导入生成器，以创建
_sass/projects/_all.scss；build-registered-projects负责此依赖，避免 Jekyll 的projects/all导入失败。
源文件与生成文件
- 源文件在 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（英文说明版本），以便系统随时间不断改进。
群组与实时聊天（Groups & realtime chat）
- 架构： 群聊客户端使用 SockJS + STOMP.js（CDN 加载），连接 Spring 后端（Pirna-spring）的
/ws-chat端点。发送到/app/groups.chat，订阅/topic/group/${groupId}；事件含 message/joinGroup/typing/heartbeat(25s)/文件图片，用 JSON event-key 集合去重并自动重连。 - 端点分支： localhost 直连
${protocol}//${host}:8589/ws-chat，生产环境走javaURI + '/ws-chat'（nginx 转发 8589）。注意：groups.js与lesson_chat.html中 8589 端口是硬编码的（代码注释标记为待迁移到 config.js）；assets/js/api/config.js已导出javaWebSocketURI但聊天代码尚未使用。 - 代码重复警告： 聊天逻辑存在于多处——规范源是 assets/js/projects/student-management-groups/groups.js（"CHAT FUNCTIONALITY" 段），但 _includes/group_dashboard.html 与 _includes/lesson_chat.html 内嵌了副本；修改后必须手动同步这些 include，否则行为不一致。
- 课程聊天约定： lesson 页面通过 frontmatter
chat: true启用，共享 backbone 群组"lessons"，以[[lesson:<url>]]标记按页面隔离。
反模式
上帝函数
- 避免做太多事情的函数。坚持单一职责原则。
隐藏的副作用
- 通过保持明确且记录良好的副作用来确保可预测性。
过度设计
- 你需要它吗 (YAGNI)： 除非现在需要，否则不要构建功能。避免推测性的泛化。
- 仅在保证正确性后才进行优化（优化前进行性能分析）。
