jsharness 1.0.0

package/.harness/docs/team-guidelines/collaboration.md

@@ -0,0 +1,556 @@
+# 通用协作规范与应急处理手册
+
+> **适用对象**: 全体产研测团队成员  
+> **目的**: 规范跨团队协作流程、争议解决机制、异常情况处理  
+> **生效日期**: 2026-05-21  
+
+---
+
+## 一、跨团队协作基本规则
+
+### 1.1 沟通渠道矩阵
+
+| 协作场景 | 正式渠道 | 非正式渠道 | 禁止行为 |
+|---------|---------|-----------|---------|
+| 需求澄清 | TaskBoard 评论 + 文档更新 | IM 即时询问 | 不留痕迹的口头约定 |
+| 技术讨论 | PR/MR 评论 + 设计文档 | IM 讨论 + 会议 | 私下绕过当事人 |
+| 缺陷协调 | Issue 系统 + 缺陷报告 | IM 通知 | 隐瞒缺陷 |
+| 进度同步 | TaskBoard + 周 会 | IM 状态更新 | 信息不透明 |
+| 紧急问题 | 电话 + IM @所有人 | - | 不通知直接处理 |
+
+### 1.2 响应时效承诺
+
+| 请求类型 | 发起方 | 接收方 | 响应时限 | 解决时限 |
+|---------|-------|-------|---------|---------|
+| 需求澄清 | PM/QA/RD | 需求分析师 | 4 工作时 | 24 工作时 |
+| 技术疑问 | RD | 方案设计师 | 8 工作时 | 48 工作时 |
+| CR 请求 | RD | Code Reviewer | 24 工作时 | 48 工作时 |
+| 缺障确认 | RD | QA | 4 工作时 | 8 工作时 |
+| 阻塞升级 | 任何人 | PM/闸门总控 | 1 工作时 | 4 工作时 |
+| 安全事件 | 任何人 | 闸门总控+安全组 | 30 分钟 | 2 工作时 |
+
+### 1.3 文档协作规范
+
+```
+谁产出的文档，谁拥有编辑权限
+下游只能评论和建议，不能直接修改
+修改需要经过原作者确认
+所有修改必须留下记录（Git commit message）
+```
+
+---
+
+## 二、争议升级机制
+
+### 2.1 争议分级与处理
+
+```
+Level 1: 同级协商（双方自行解决）
+    │ 无法解决
+    ▼
+Level 2: PM 调解（PM 协调双方沟通）
+    │ 无法解决
+    ▼
+Level 3: 闸门总控裁决（技术争议由闸门总控判定）
+    │ 仍有异议
+    ▼
+Level 4: 技术委员会仲裁（跨部门高层决策）
+```
+
+#### Level 1: 同级协商
+
+**适用于**：小的意见分歧、风格偏好、非阻塞问题
+
+**做法**：
+- 在 PR/MR 评论中理性讨论
+- 引用 Rule/Skill/设计文档作为依据
+- 尊重对方的专业判断
+- 以「对事不对人」的原则沟通
+
+**时限**：3 个工作日内解决
+
+#### Level 2: PM 调解
+
+**适用于**：需求理解分歧、优先级争议、资源协调问题
+
+**做法**：
+- 任意一方发起调解请求（通知 PM）
+- PM 组织双方会议或异步讨论
+- PM 基于业务优先级给出建议
+- PM 不做技术判断（只协调资源和优先级）
+
+**时限**：2 个工作日内给出调解建议
+
+**触发条件**：
+- Level 1 协商超过 3 天无进展
+- 涉及多个团队的协调问题
+- 任一方明确表示需要调解
+
+#### Level 3: 闸门总控裁决
+
+**适用于**：技术方案争议、安全判断分歧、规范性争议
+
+**做法**：
+- 提交争议说明文档（双方观点 + 依据）
+- 闸门总控独立评估（不受任何一方影响）
+- 做出裁决并说明理由
+- **裁决具有强制效力**
+
+**时限**：2 个工作日内做出裁决
+
+**裁决格式**：
+
+```markdown
+# 争议裁决: {争议主题}
+
+## 争议双方
+- 甲方: {姓名/角色} — 观点: ...
+- 乙方: {姓名/角色} — 观点: ...
+
+## 甲方论据
+（引用的文档、规则、数据等）
+
+## 乙方论据
+（引用的文档、规则、数据等）
+
+## 评估过程
+（闸门总控的分析过程）
+
+## 裁决结论
+✅ 甲方胜诉 / ✅ 乙方胜诉 / 🔄 折中方案
+
+## 裁决理由
+（基于什么原则/规则做出的判断）
+
+## 执行要求
+- {具体需要做的事情}
+- 执行期限: {日期}
+
+---
+裁决人: {闸门总控}  日期: {YYYY-MM-DD}
+```
+
+#### Level 4: 技术委员会仲裁
+
+**适用于**：
+- Level 3 裁决仍有重大异议
+- 涉及公司级技术战略
+- 影响面超过单个项目
+
+**做法**：
+- 由技术总监/CTO 级别组成临时仲裁小组
+- 听取各方陈述
+- 做出最终仲裁
+
+**时限**：5 个工作日内
+
+### 2.2 常见争议处理指引
+
+| 争议类型 | 典型场景 | 首选处理方式 | 仲裁依据 |
+|---------|---------|-----------|---------|
+| 需求理解不同 | PM 和开发对需求理解不一致 | PM 组织三方会议 | 需求文档 + 验收标准 |
+| 技术方案分歧 | 两个方案各有优劣 | 方案对比文档 + 闸门裁决 | ADR + 技术评估 |
+| 代码风格差异 | 个人偏好不同 | 统一遵循 coding-standard.md | 编码规范 Rule |
+| 优先级争夺 | 多个任务争抢资源 | PM 基于业务价值排优先级 | 产品路线图 |
+| 质量标准分歧 | 测试和开发对 bug 严重度认定不一 | 引用缺陷分级标准 | qa-team.md 缺陷分级 |
+| 安全判断分歧 | 是否构成安全漏洞 | 升级到闸门总控 | security-baseline.md |
+| 进度压力 | 赶进度 vs 保质量 | 质量底线不可妥协 | 流程纪律 Rule |
+
+---
+
+## 三、应急处理流程
+
+### 3.1 生产事故应急
+
+```
+生产事故发生
+    │
+    ▼
+① 立即通知（15分钟内）
+    ├── 通知值班人员
+    ├── 通知技术负责人
+    └── 通知 PM（如影响用户）
+    │
+    ▼
+② 初步定级（30分钟内）
+    ├── P0: 全站/核心功能不可用
+    ├── P1: 部分功能受严重影响
+    └── P2: 轻微影响
+    │
+    ▼
+③ 成立应急小组
+    ├── P0/P1: 技术负责人 + 相关开发 + DBA（如需要）
+    └── P2: 值班人员处理
+    │
+    ▼
+④ 抢修（按紧急程度）
+    ├── 可直接修 → 走热修复变体流程
+    ├── 需要排查 → 先止血（回滚/降级），再排查根因
+    └── 影响扩大 → 考虑全量回滚
+    │
+    ▼
+⑤ 恢复验证
+    ├── 功能验证
+    ├── 数据一致性检查
+    └── 监控确认正常
+    │
+    ▼
+⑥ 事后复盘（72小时内）
+    ├── 编写事故报告
+    ├── 根因分析（5 Whys）
+    ├── 改进措施制定
+    └── Follow-up 跟踪
+```
+
+**热修复流程（ Harness 变体）**：
+
+```
+紧急问题 → PM 路由为 hotfix 类型
+    │
+    ▼
+快速需求分析（压缩版，1-2小时）
+    │
+    ▼
+最小方案设计（仅修bug部分）
+    │
+    ▼
+⚡ 快速闸门（仅检查安全+回归风险）
+    │
+    ├── 安全无风险 → PASS
+    └── 有安全风险 → BLOCK（必须正常流程）
+    │
+    ▼
+紧急开发（只改必要的代码）
+    │
+    ▼
+加速代码审查（至少1人审查，重点看安全和回归）
+    │
+    ▼
+核心回归测试（不跑全量，聚焦影响面）
+    │
+    ▼
+快速部署 + 全量监控
+    │
+    ▼
+事后补全文档和全量测试
+```
+
+### 3.2 人员突发缺席处理
+
+```
+发现关键人员缺席
+    │
+    ▼
+① 立即评估影响
+    ├── 该人员正在进行的阶段/任务
+    ├── 交接状态如何
+    └── 紧急程度
+    │
+    ▼
+② 通知 PM
+    │
+    ▼
+③ 临时接替安排
+    ├── 有交接文档 → 其他人接力
+    ├── 无交接文档 → 紧急知识转移
+    └── 无法替代 → 调整优先级/延期待命
+    │
+    ▼
+④ 更新 TaskBoard
+    │
+    ▼
+⑤ 人员回归后同步
+```
+
+### 3.3 外部依赖故障处理
+
+```
+外部依赖不可用
+    │
+    ▼
+① 确认故障范围
+    ├── 是完全不可用还是降级？
+    ├── 预计恢复时间？
+    └── 有无备用方案？
+    │
+    ▼
+② 评估影响
+    ├── 哪些功能受影响？
+    ├── 能否降级运行？
+    └── 用户感知如何？
+    │
+    ▼
+③ 决策
+    ├── 短暂等待（< 1小时） → 暂停等待
+    ├── 中等时长（1-4小时） → 降级方案
+    ├── 长时间（> 4小时） → 切换备用方案 / 暂停功能
+    └── 不可恢复 → 启动应急预案
+    │
+    ▼
+④ 通知相关方
+    ├── 内部团队
+    └── 受影响的用户（如需要）
+```
+
+---
+
+## 四、流程例外管理
+
+### 4.1 申请流程例外的条件
+
+**只有以下情况可以申请跳过或简化流程**：
+
+| 例外的类型 | 允许的条件 | 审批人 | 附加要求 |
+|----------|----------|-------|---------|
+| 跳过某阶段 | 该阶段的产出已在之前完成 | 闸门总控 | 提供已有产物证明 |
+| 简化流程 | 使用预定义的流程变体 | PM | 选择正确的变体 |
+| 并行执行阶段 | 阶段间无强依赖 | PM + 相关负责人 | 书面确认风险可控 |
+| 加急处理 | P0 级生产事故 | 技术负责人 + PM | 事后补全所有文档 |
+| 规则豁免 | 特殊情况确实无法遵守规则 | 闸门总控 | 说明豁免理由和期限 |
+
+### 4.2 例外申请流程
+
+```markdown
+# 流程例外申请
+
+## 申请人
+- 姓名: 
+- 角色: 
+- 日期: 
+
+## 申请内容
+- 申请哪种例外: ___
+- 涉及哪个任务: TASK-YYYY-NNN
+- 当前所处阶段: 
+
+## 申请理由
+（详细说明为什么需要例外）
+
+## 影响评估
+- 对质量的影响: 
+- 对安全的影响: 
+- 对可追溯性的影响: 
+- 对团队协作的影响: 
+
+## 缓解措施
+（如何降低例外带来的风险）
+
+## 事后补救计划
+（例外结束后如何补齐缺失的部分）
+
+## 审批
+- PM 意见: [同意/不同意] 签字:___
+- 闸门总控意见: [同意/不同意] 签字:___
+```
+
+### 4.3 禁止例外的场景
+
+**以下情况不允许任何形式的例外**：
+
+- ❌ 安全检查（无论多紧急，安全红线不可跨越）
+- ❌ 生产环境数据库变更（必须有完整流程）
+- ❌ 涉及用户隐私数据的操作
+- ❌ 认证/授权机制的变更
+- ❌ 支付/财务相关的变更
+
+---
+
+## 五、知识管理与共享
+
+### 5.1 交接制度
+
+**人员变动时必须完成的知识交接**：
+
+| 交接内容 | 交付物 | 接收人确认 |
+|---------|-------|-----------|
+| 当前手头任务状态 | TaskBoard 最新状态 | ☑ |
+| 进行中需求/设计的上下文 | 需求文档 + 设计文档 + 个人笔记 | ☑ |
+| 未闭环的技术决策 | ADR 草稿 + 决策背景 | ☑ |
+| 已知问题和坑 | 问题清单 + 解决方案/Workaround | ☑ |
+| 关键联系人 | 联系清单 + 对接事项 | ☑ |
+
+**交接文档模板**：
+
+```markdown
+# 工作交接: {姓名} → {接替人}
+
+## 交接日期: YYYY-MM-DD
+
+## 一、当前任务状态
+| 任务ID | 名称 | 当前阶段 | 完成度 | 注意事项 |
+|-------|------|---------|-------|---------|
+| | | | | |
+
+## 二、进行中的需求/设计上下文
+### {任务名称}
+- **当前进展**: 
+- **下一步要做什么**: 
+- **需要注意的坑**: 
+- **关键决策背景**: 
+
+## 三、未闭环的技术决策
+- {ADR草稿或决策说明}
+
+## 四、已知问题
+| 问题 | 状态 | Workaround | 跟踪链接 |
+|-----|------|-----------|---------|
+| | | | |
+
+## 五、关键联系人
+| 联系人 | 角色 | 对接事项 | 备注 |
+|-------|------|---------|------|
+| | | | |
+
+## 六、账号/权限移交
+- [ ] Git 仓库权限
+- [ ] 服务器/环境权限
+- [ ] 第三方服务账号
+- [ ] 文档/知识库权限
+
+---
+**交接人签字**: _______________ 日期: ___
+**接收人签字**: _______________ 日期: ___
+**PM 确认**: _______________ 日期: ___
+```
+
+### 5.2 最佳实践共享
+
+**鼓励的行为**：
+- 在 `dev-map/decisions.md` 中记录有价值的经验教训
+- 在团队周会上分享踩过的坑
+- 将通用解决方案提炼为 Skill 补充
+- 主动更新 Rule 让规则更完善
+
+**共享渠道**：
+- 每双周技术分享会（每人轮流）
+- 内部 Wiki / 知识库
+- ADR 作为永久性技术资产
+
+---
+
+## 六、工具与平台使用规范
+
+### 6.1 Harness 相关命令全览
+
+```bash
+# ===== 核心功能 =====
+
+# 门禁检查（所有人可用）
+node .harness/gate/index.js                        # 完整检查
+node .harness/gate/index.js --report               # 生成报告
+node .harness/gate/index.js --save-baseline        # 保存基线
+node .harness/gate/index.js --baseline             # 对比基线
+
+# 工作流校验
+node .harness/workflow/validate.js                 # 流程完整性检查
+
+# TaskBoard 查看
+cat .harness/task-board.md                         # 当前看板状态
+
+# ===== 规则查询（所有人可用）=====
+
+# 流程纪律（所有人必读）
+cat .harness/rules/global/process-discipline.md
+
+# 编码规范（开发必读）
+cat .harness/rules/global/coding-standard.md
+
+# 提交规范（开发必读）
+cat .harness/rules/global/commit-convention.md
+
+# 安全红线（所有人必读）
+cat .harness/rules/global/security-baseline.md
+
+# Web 应用特有规则（前后端开发必读）
+cat .harness/rules/project/web-specific.md
+
+# ===== 技能参考 =====
+cat .harness/skills/build.md           # 构建技能
+cat .harness/skills/test-unit.md       # 单元测试
+cat .harness/skills/test-e2e.md        # E2E 测试
+cat .harness/skills/test-api.md        # API 测试
+cat .harness/skills/lint-check.md      # 静态检查
+cat .harness/skills/code-review.md     # 代码审查
+cat .harness/skills/docker-build.md    # Docker 构建
+cat .harness/skills/docs-update.md     # 文档更新
+
+# ===== Agent 契约（了解他人职责）=====
+cat .harness/agents/{role}/contract.yaml
+# role: project-manager / requirements-analyst / solution-designer
+#       gate-controller / developer / code-reviewer / tester
+
+# ===== Prompt 模板（了解 AI 协作方式）=====
+cat .harness/agents/prompt-templates.md
+
+# ===== Dev Map（项目知识库）=====
+cat .harness/dev-map/overview.md                        # 总览
+cat .harness/dev-map/frontend/{structure,components,...}.md  # 前端
+cat .harness/dev-map/backend/{structure,database,...}.md     # 后端
+cat .harness/dev-map/decisions.md                       # ADR
+```
+
+### 6.2 外部工具集成（MCP）
+
+当前 MCP 集成状态（详见 `.harness/mcp/config.yaml`）：
+
+| 阶段 | 已集成的 Tool | 状态 |
+|-----|-------------|------|
+| 只读 | Git status/diff/PR读取 | ✅ 已配置 |
+| 只读 | CI 构建状态/日志读取 | ✅ 已配置 |
+| 只读 | Issue 列表/详情读取 | ✅ 已配置 |
+| 写入 | CI 触发构建（含审批流） | 📋 已规划 |
+| 写入 | PR/MR 创建和评论 | 📋 已规划 |
+| 写入 | Docker 构建推送 | 📋 已规划 |
+| 闭环 | 制品上传/部署触发 | 📋 远期规划 |
+| 闭环 | 状态回写（Jira→TaskBoard） | 📋 远期规划 |
+
+---
+
+## 七、持续改进机制
+
+### 7.1 反馈收集渠道
+
+| 渠道 | 用途 | 响应方式 |
+|-----|------|---------|
+| 每双周 Retrospective | 团队流程回顾 | Action Item 跟踪 |
+| 匿名意见箱 | 敏感问题反馈 | 定期汇总处理 |
+| 规范 Issue | Rule/Skill 改进提案 | /opsx:propose 流程 |
+| 1:1 沟通 | 个人的困惑和建议 | 记录并跟进 |
+
+### 7.2 规范更新流程
+
+```
+发现改进空间 → 提出 Proposal（/opsx:propose）
+    │
+    ▼
+团队讨论评审
+    │
+    ▼
+达成共识 → 更新对应文档
+    │
+    ▼
+通知全体成员
+    │
+    ▼
+培训/宣贯（如重大变更）
+    │
+    ▼
+生效 + 观察
+```
+
+### 7.3 季度 Review 检查清单
+
+每季度末执行：
+
+- [ ] Rule 规则是否仍适用？有无需要新增/修改/废止的？
+- [ ] Skill 步骤是否有优化空间？
+- [ ] Workflow 流程变体是否需要调整？
+- [ ] Gate 门禁阈值是否需要更新？
+- [ ] Agent 契约是否需要根据实际情况调整？
+- [ ] dev-map 是否与代码保持一致？
+- [ ] 团队对规范的遵从度如何？有哪些常见违规？
+- [ ] 有哪些流程瓶颈可以优化？
+
+---
+
+*本规范是全员通用的协作准则和异常处理手册。请每位团队成员熟记于心，在遇到不确定的情况时以此为参考。*