通用研发工程方法论

1. 协作流程

方案先行

• 不要自己制定方案就开始执行。如果打算采用的方案与当前实现不同（架构调整、新的标识/协议/数据结构、跨服务行为变更等），必须先把方案完整呈现给开发者，开发者确认后才能开始写代码。
• "先分析后动手"：需求不明确或存在多种可行实现时，列出方案与取舍供开发者选择，不要擅自选定。
• 已经开始实施后发现需要换方案，同样先停下来说明并等确认。

最小实现

• 严格按需求范围实现，不过度实现、不过度设计：不做需求没有要求的功能、交互、配置项、扩展点或"以防万一"的抽象。
• 需求明确列出字段或行为时，以需求清单为准，不自行扩大范围。
• 实施过程中发现实现范围开始超出需求描述时，先停下来与开发者确认是否需要，确认前不加码。

2. Git 纪律

提交授权

• 不自动提交。只有包含"commit"、"提交"、"push"、"推送"关键词的明确指令才允许提交或推送，且执行前仍需确认。
• "fix it"、"改一下"、"修复 build 错误"等表述仅表示修改代码，不构成提交指令。
• 禁止因任务延续、TODO 收尾等自动触发机制擅自提交。

分支保护

• 永远不直接推主干分支（master/main）。 经 feature/fix 分支 + PR/MR 合入。
• 新需求先取最新主干（git fetch origin），再从最新 origin/master 建新分支；独立新需求直接用 git worktree 创建（见下），无需切换当前检出。
• 是否新建分支必须先问研发确认；已有功能分支的后续修改默认在原分支继续。
• 在主干分支上收到改代码请求时，必须先建分支再动手；push 前必须检查当前分支。

仓库级保护设置——检查项目的默认分支与 GitHub 开源项目时执行；有权限时先征求研发同意再设置，无权限或 API/平台不支持时提示研发自行设置，不静默跳过：

• 默认分支（master/main）启用分支保护：禁止直推（要求 PR 合入）、禁止 force push、禁止删除分支。参考：gh api -X PUT repos/<org>/<repo>/branches/master/protection，关键项 allow_force_pushes=false、allow_deletions=false、enforce_admins=true、required_pull_request_reviews 按团队情况设审批数（单人仓库可用 0）。
• GitHub 开源项目另需启用两项仓库设置：
  • Automatically delete head branches（PR 合并后自动删除头分支）：gh api -X PATCH repos/<org>/<repo> -F delete_branch_on_merge=true；
  • Release immutability（release 不可变，防篡改已发布产物）：API 暂可能不支持或无权限，此时提示研发在仓库 Settings 中自行开启。

独立需求与 git worktree

• 需求开发开始前，先与研发确认这是否为一个独立新需求：
  • 是 → 用 git worktree 开辟独立并行工作区，避免与当前检出上的其他工作互相干扰——不 stash、不切分支、不破坏依赖安装与构建缓存；
  • 否（小修、延续已有需求、文档微调等）→ 在现有检出上按常规建分支即可，不额外开 worktree。
• 一个需求一个分支、一个 worktree：worktree 目录名与分支名共用同一需求标识（分支可带 feat/ 等类型前缀）。git 不允许同一分支被两个 worktree 同时检出，天然保证一一对应。
• 基于最新主干创建：git fetch origin && git worktree add -b feat/<req> ../<repo>.worktrees/<req> origin/master；需求依赖另一个未合并的需求分支时，显式基于该分支创建并向研发说明。
• worktree 内首次初始化注意：submodule 需 git submodule update --init；依赖目录（node_modules 等）与构建缓存不共享，按需重装。
• 需求完成（PR 合并）后及时清理：git worktree remove + git branch -d，失效条目定期 git worktree prune；禁止长期堆积废弃 worktree。

跨仓库一致性

• 一次修改涉及多个仓库时，分支名保持一致，体现本次改动核心内容（如 feat/xxx-yyy）。
• 一个需求跨多仓库时，所有仓库的分支名/worktree 名统一为该需求标识，各仓库 PR 标题注明同一需求，便于跨仓库追踪与批量合并。

3. 验证策略

• 不在本机执行重型构建/运行验证（docker build/run 等），AI 不自行启动。
• 以各仓库的编译 + 自动化测试作为完成验证手段（如 go build/test、tsc --noEmit、vitest run，按技术栈选择）。
• 镜像与部署验证交给 CI 或具备资源的环境；所需私有凭证由执行环境提供。

4. 接口与标识符设计原则

标识符职责分离

任何系统里两类标识必须严格分工，不可混用：

• 接口入参统一用主键，参数名用 id，不得用可读标识的命名承载数字 ID。
• 跨层使用（入参 → 消息路由）前，由服务端用主键查库换取可读标识再拼接 topic。
• 历史调用可做归一兜底（纯数字按主键查、否则视为可读标识），查不到直接报"不存在"，不等超时；归一是兜底而非许可，新代码不得依赖。

接口契约

• 字段命名风格前后端统一（如 snake_case），禁止双套命名兼容输出。
• 列表接口统一分页契约：请求 page（从 1 起）+ page_size（设上限），响应 data/page/total/page_size。
• 查询/重置/切换每页条数时页码重置为 1。

实时数据接口

• 页面需要实时展示数据（监控、日志、任务进度、消息、状态流转等）时，优先考虑 WebSocket 或流式接口（SSE / HTTP streaming），避免前端高频轮询。
• 方案先行，向研发确认：是否采用该类接口必须基于需求分析并与研发确认，不得擅自定。分析维度：
  • 更新频率与延迟容忍：亚秒级更新或需服务端主动推送 → WebSocket/SSE；低频（秒级以上）且容忍延迟 → 常规轮询即可，不过度设计；
  • 通信方向：仅服务端单向推送 → SSE（基于 HTTP，网关/代理/鉴权更友好）；客户端也要实时发送 → WebSocket；
  • 配套机制同步设计：断线重连、心跳、鉴权、消息顺序、背压。
• 采用后，消息契约（事件类型、数据结构、错误码）同样遵循接口契约与展示分离原则。

展示与数据分离

• 用户可见文案由前端定义，后端只返回稳定的 code/枚举值；前端本地维护映射表，未知 code 回退兜底文案。
• 禁止把底层技术错误（rpc error、connection refused 等）透传给用户，前端判断内容做友好包装，告知可能原因和解决方向。
• 同一概念在同一段文案中不得中英文混用；专有名词（服务名、容器名、命令）保留英文。
• 文案中禁止后置括号补充解释；解释融入句子或作为独立辅助说明行。
• 用词清晰不自造词，同一事物在所有页面/提示/接口文案中同称呼。

5. 架构师职业习惯

• 动手前先画清项目拓扑：各服务端口、路由前缀、代理关系、职责边界（哪个服务负责执行什么）。
• 涉及多服务的行为变更，先确认协议/数据结构在各端的同步改动点，再动手。
• 权限与安全随接口同步设计：每个新增/修改/删除的接口都要同步考虑权限控制，旁路入口（快捷键、右键）加同样判断。
• 日志分层：stdout 分级日志（高频用 debug）+ 持久化业务/审计日志分离，关键链路出入口必须有 info 日志。

本地工作区布局

• 工作区根为 ~/Workspace（~/ws 为其软链）；GitHub 项目统一存放于 ~/Workspace/github/。
• 按 <owner>/<repo> 两级组织：本人仓库在 github/linuxsuren/<repo> 下，仓库名用 kebab-case；第三方项目同样按其 owner 归档，不与本人仓库混放。
• 本地仓库 origin 统一使用 https://github.com/<owner>/<repo>.git。
• git worktree 统一放在仓库同级目录：<repo>.worktrees/<需求标识>/，与「独立需求与 git worktree」规则一致。
• clone 新仓库、开辟 worktree、定位项目时按此布局操作；发现不符布局的路径，可建议研发归位。