project-aware-coding

结合项目上下文写代码

目标不是把新代码写得“像项目”，而是在动手前理解项目已经形成的业务约束、真实消费者和历史经验，减少重复踩坑。项目已有实现优先作为参考样本，但仍要判断它是否适用于当前需求、版本和调用链。

边界

• 只修改用户当前需求必需的代码、配置、测试和文档，不顺手重构或扩展未来能力。
• 先检查工作区、分支、worktree 和仓库说明，保留其他人或其他会话的未知改动。
• 删除文件、函数、注释、测试、兼容逻辑或数据前单独说明理由并取得确认。
• 实现授权不包含 commit、push、部署、创建 PR、外部评论或数据库写入；这些动作需要当前批次的明确授权。
• 仓库若提供专用开发 Skill 或规范工具，例如 goalfy-coding，按当前任务读取并组合使用，但不得让其自动扩大本次写入范围。

工作流

1. 固定目标与现场

读取适用的 AGENTS.md、CLAUDE.md、仓库级 Skill 和开发文档。检查 git status、当前分支、HEAD、worktree 和已有 diff；涉及远端基线时先 git fetch，仅审查当前未提交改动时不为形式强制刷新远端。

用可观察结果明确本次需求：谁在什么条件下触发，现有行为哪里偏离，完成后谁能看到什么变化。若信息能从代码、配置、测试或关联材料中确认，先自行读取；只有关键选择会实质改变方案时才询问用户。

2. 还原最小完整机制

追踪与改动有关的真实链路：

输入或触发
→ 入口与生产者
→ 状态或数据变化
→ 真实消费者
→ 用户可见结果
→ 失败、重试、恢复或终态

只展开与当前需求有关的上下游。不能根据函数名、字段名或注释猜用途；读取方法体、调用方、被调用方、注册点、配置来源和必要运行时契约。

共享配置还要与构造参数交叉检查：当同一个配置对象或字段被多个构造器、工厂或 wrapper 复用，而调用时又传入 bucket、tenant、region、namespace、资源 ID 等会改变语义的参数，列出全部生产调用方及其真实实参组合，区分“配置属于谁”和“本次 client 操作谁”。至少让默认消费者和一个非默认消费者走通同一验证链；默认实例的测试不能代表其他 bucket、租户或资源。

3. 按风险参考项目已有实现

使用 rg 从同仓库开始寻找最接近的样本，常用线索包括业务字段、接口路径、错误码、注册方法、消费者名称、配置键和测试名称。按以下优先级选择真正有参考价值的代码：

1. 与本次改动共享真实消费者或协议链路；
2. 同模块、同业务角色或同一状态生命周期；
3. 有针对性测试或运行证据；
4. 当前仍在使用且版本接近；
5. 历史提交明确记录过踩坑原因。

简单文案、局部条件或单点字段改动，通常参考最邻近的一处实现即可，不做无边界考古。涉及协议、Schema、序列化、数据库约束、跨服务接口、并发、幂等、权限或兼容行为时，扩大到真实消费者、相关测试和必要 git log / git blame，确认项目曾经为何选择当前写法。

参考时回答三个问题：

• 哪部分约束与当前需求相同，可以沿用；
• 旧设计解决或规避了什么实际问题；
• 哪部分场景、版本或消费者不同，不能机械复制。

已有代码是经验，不是绝对规则。若它已过时、有缺陷或不适用于新场景，可以偏离；但要写清差异来自新需求、依赖版本还是消费者能力，并用针对性测试验证。不要因为某写法符合通用标准、看起来更优雅或外部项目流行，就跳过本项目真实链路。

找不到可靠样本时，记录搜索过的范围和关键词，再查真实消费者实现、官方当前契约或执行最小探针。不要为了满足流程强行选择不相关代码，也不要仅因没有先例就阻塞低风险实现。

4. 设计并实施最小改动

涉及新增或调整模块职责、接口与依赖方向时，使用 $codebase-design 检查高内聚、低耦合；普通局部修改不额外加载。

优先复用项目现有入口、抽象、错误处理、命名和测试结构，但只复用当前需求真正需要的部分。每个 diff hunk 都应能对应到需求、已确认根因、必要测试或项目强制工具输出；无法对应的格式化、helper 抽取、依赖升级和未来兼容应移除或先征求授权。

改动 Schema、API 或协议时，区分“标准允许”和“项目真实消费者支持”。例如某个 JSON Schema 关键字在规范中合法，不代表当前模型、SDK、网关或工具注册链路接受；使用与项目相同的消费路径和样例验证，不把单一历史结论错误推广到所有协议或版本。

遵循仓库现有结构完成最小实现，使用当前环境提供的精确编辑工具。不要覆盖未知改动，不修改无关文件，不为让测试变绿而放松断言、跳过测试或隐藏错误。