| name | dev-constraints |
| description | Codex 的项目开发约束技能。涉及代码修改、代码阅读、业务上下文建立、文档编辑、查询代码逻辑、多文件实现时使用。它会约束任务启动、文档优先级、工作区与正式区的使用方式、代码变更后的文档同步，以及对外变更时的确认规则。 |
开发约束
本技能定义项目任务在关键节点必须执行的动作。它不替代具体业务技能，也不替代实现计划，但会覆盖这些任务在上下文建立、文档处理、代码修改与验收时的默认行为。
查询类任务只需要执行“开始任务时”。不涉及文件修改时，可以不进入后续的文档同步和验收环节。
一、开始任务时
1. 长任务判断
出现以下任一情况时，应同时使用 task-control 做持久化记录：
- 需要跨文件探索再整合输出
- 涉及 3 个及以上关键编辑步骤
- 预计会跨多轮交互或中断后恢复
- 涉及对外变更（接口、数据库、配置、调度、消息）
2. 工作区检查
开始前先检查项目中是否已有工作区性质的未合并内容。优先检查：
.codex/docs/- 仓库自带的草稿、工作区、draft、work 目录
如果存在上次任务遗留的未合并内容，应先判断本次是否复用，而不是直接覆盖。
3. 文档优先于代码
建立业务上下文、理解代码逻辑、准备修改代码前，优先读取文档，再读代码：
- 域概览或总览文档
- 主题级或模块级文档
- 技术速查、技术参考、架构说明
若同时存在工作区文档与正式文档，优先读取工作区版本。
4. 文档缺失处理
如果项目既没有工作区文档，也没有正式文档，应先提示用户：
- 当前缺少业务上下文文档
- 直接改代码风险较高
- 是否先使用
docs-desc-generation 补一版最小业务域文档
只有在用户明确接受跳过时，才直接进入代码探索。
5. 基础设施查询快速通道
如果任务纯粹是查询基础设施信息，例如表结构、索引、配置、数据库数据、队列主题等：
- 用户已给出精确信息时，优先使用
dev-small-tool 直接查询
- 用户只给业务含义时，先从文档或代码中确认准确名称，再使用
dev-small-tool 查询
- 关键名称不要凭记忆猜测
这类任务可以不进入完整的文档→代码探索流程。
二、修改代码时
1. 先识别外部影响
进入代码修改前，先识别本次改动是否影响以下内容：
- HTTP API
- 数据库结构或核心 SQL
- 配置项
- 定时任务
- MQ / Event / Consumer / Listener
- 其他对外契约
2. 对外变更必须确认
如果改动涉及上述对外契约，而用户没有明确要求或确认，必须暂停并征求确认，不得自行决定。
3. 同步更新工作区文档
代码变更完成时，如项目存在工作区文档区，应把本次行为变化同步更新到工作区文档。
工作区不存在时：
- 优先从正式文档复制初始化
- 正式文档也不存在时，新建最小骨架文档
4. 入口变化要补流程说明
如果变更涉及新增或修改以下内容，应检查文档里是否已有对应流程说明：
- API 入口
- 事件监听
- 定时任务
- 消息消费
- 核心异步链路
若没有，应在对应文档中补齐。
5. 技术速查同步
若项目有 TECH-REF、技术速查、架构索引、问题定位文档等，应在以下情况同步更新：
- 新增核心代码入口
- 新增核心表或索引
- 新增异步事件或链路
- 发现或新增关键问题定位方式
- 重构改变关键结构
- 发现高风险大文件或上帝类
6. 编码约束
- 保持原有分层，不跨层偷跑
- 关键名称从代码和真实元数据中确认，不凭记忆猜测
- 变更尽量小而清晰，避免把结构调整和业务改动混在一起
- 如涉及真实元数据（表、索引、配置、消息主题），优先从代码、配置和真实环境线索中确认
三、编辑文档时
1. 优先编辑工作区文档
如果项目区分工作区文档和正式文档：
2. 仅小修正可直改正式文档
只有在以下条件同时满足时，才可以直接改正式文档：
3. 保持代码与文档同任务同步
只要代码行为变更，就尽量在同一任务里完成文档同步，而不是留到以后补。
四、需要确认时
以下情况必须等待用户确认：
- 需求理解有歧义
- 涉及对外变更
- 需要覆盖、丢弃或还原已有工作区内容
- 验收完成，需要用户确认结果
五、完成任务时
按任务类型自检：
- 查询类：结果准确，来源清楚
- 实现类：功能完整，风险已说明，本地验证已尝试，相关文档已同步
- 缺陷修复：根因明确，原问题不再出现，有验证记录
- 文档类：内容准确、位置正确、与当前实现一致
如果项目存在工作区与正式区区分，不自动合并正式文档，除非用户明确要求。
