Genarrative/docs/project-memory/shared-memory/team-conventions.md

团队协作约定

用途：约定 3 名开发人员在各自本地开发环境和 Agent 中协作开发、共享项目记忆的方式。

基本模式

• 每位开发人员在自己的电脑上使用本地 Agent。
• 每位开发人员本地拉取同一个项目仓库，独立修改代码、运行测试、提交分支。
• 团队共享内容优先放在本仓库 docs/project-memory/ 与 docs/ 中，通过 Git 同步。
• 不共享个人 ~/.hermes 目录。

共享与禁止共享

推荐共享：

• docs/project-memory/shared-memory/ 团队级长期记忆
• docs/project-memory/plans/ 阶段性实施计划
• docs/project-memory/todos/ 已确定需要执行、但尚未进入实施的共享 TODO 计划
• .hermes/skills/ Hermes 专用仓库级 skills
• docs/ 中 PRD、设计、技术、经验、审计、查询手册
• AGENTS.md 项目级 Agent 约束
• docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md Agent 执行细则

禁止提交：

• 个人 ~/.hermes/config.yaml
• 个人 ~/.hermes/.env
• 个人 ~/.hermes/sessions/
• API Key、Token、Cookie、认证文件
• 个人本地私密路径和个人隐私信息
• 构建产物、日志、缓存、数据库 dump

开发前

1. 拉取最新代码。
2. 阅读 AGENTS.md。
3. 复杂任务阅读 docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md。
4. 阅读 docs/project-memory/shared-memory/ 中与任务相关的文件。
5. 阅读 docs/README.md 和任务相关分类 README。
6. 阅读对应 PRD、设计、技术、经验或审计文档。
7. 如果文档不足以指导编码，先补充或修正文档。

开发中

• 保持修改范围聚焦，不做无关重构。
• 复用、修改、扩展现有系统优先，避免新建重复系统或页面。
• 新增 Markdown 文档时，文件名必须以分类标签开头，格式为 【标签名】中文标题-日期.md；只在任务需要时重命名历史文档，避免无关大 diff。
• 涉及中文文本时注意 UTF-8 编码和乱码排查。
• 涉及后端时遵循 DDD 分层，不把业务真相下沉到前端或临时兼容层。
• 对已明确退役且不存在现役调用方、公开契约、持久化数据、活跃实例或迁移要求的对象，不新增历史兼容代码、维持退役行为的防御性兼容测试、墓碑注释或墓碑文档；权威文档直接更新为当前状态。公开 API、持久化数据、SpacetimeDB schema、跨版本重放、活跃实例和正式迁移仍须保留最小化、白名单化的必要兼容及契约或迁移测试，并在迁移完成后同步删除。
• 运行时日志禁止对完整配置、应用状态或 provider client 做递归 Debug 输出；当前 AppConfig、AppState、AppStateInner、SpacetimeClientConfig 与 SpacetimeClient 必须保持封闭的手写安全摘要，并用唯一哨兵测试锁定顶层与可独立格式化路径。其它仍使用派生 Debug 的历史 provider 类型不得新增整对象日志调用，后续按类型独立脱敏。新增字段默认不进入摘要，确需排障时只增加枚举、数值、布尔值或是否配置等非敏感字段。
• packages/shared 用于前后端 DTO、公开契约及跨页面复用的无业务真相 UI 组件和纯工具；不得把领域规则、后端副作用或正式状态放入其中。
• 修改 /api/external/v1 的路由、HTTP 方法、请求 / 响应 DTO、请求头、状态码、鉴权或异步语义时，必须同批更新 docs/openapi/genarrative-external-v1.openapi.json 和对应契约测试；Rust 实现与 OpenAPI 未对齐时不得完成、提交或发布。
• maincloud / Maincloud / MAINCLOUD 相关代码、脚本、测试、环境变量、命令和文档要求均视为历史残留，禁止新增、运行或引用；API smoke 统一使用 npm run dev:api-server 与 /healthz。
• 涉及 SpacetimeDB 表结构、发布或迁移时，先看 SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md 和 SPACETIMEDB_TABLE_CATALOG.md。
• 涉及生产发布、服务器配置、Jenkins Job 重建或回滚时，先看 PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md。

开发后

1. 运行与修改范围匹配的测试或验证命令。
2. 更新相关 docs/ 文档。
3. 新增或沉淀 Markdown 文档时，确认文件名已使用 【标签名】 前缀。
4. 若产生长期有效知识，更新 docs/project-memory/shared-memory/。
5. 若形成 Hermes 专用可复用流程，考虑沉淀到 .hermes/skills/。
6. 提交代码时，提交标题使用中文；标题后逐行写明本次提交修改了什么，每条变更单独一行。

文档阅读顺序

通用任务建议：

1. README.md
2. AGENTS.md
3. docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md
4. docs/project-memory/shared-memory/
5. docs/README.md
6. 任务所属分类：docs/design/、docs/technical/、docs/planning/、docs/prd/、docs/reference/、docs/tracking/、docs/operations/

后端任务建议：

1. docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
2. docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
3. 任务相关 crate README、源码和当前专题文档

共享记忆更新准则

适合更新：

• 新增稳定架构约定
• 新增长期开发流程
• 已验证的踩坑和排障步骤
• 重要接口契约变化
• 团队协作规范变化
• 文档索引或阅读顺序变化

不适合更新：

• 一次性临时计划
• 未验证猜测
• 个人偏好和个人路径
• 敏感信息
• 大段聊天记录