该技能名称为 code,定位是编码实现阶段的技能,强调以测试驱动开发(TDD)方法编写代码。当用户说 "implement"、"write"、"add"、"code"、"feature"、"build" 或正在实际编写解决方案时,适合使用该技能。
一、用途与定位 该技能负责实现阶段,要求遵循测试驱动开发与项目既有约定。它本身不直接提供具体语言实现,而是将通用实现原则委托给相关技能:test-driven-development 负责红/绿/重构纪律与失败测试先行规则;verification-before-completion 负责在声称完成之前提供证明。同时可选的 obra/superpowers 伴生技能提供通用方法论,TeaTree 保留项目专属工作流。
二、依赖与前置技能 所需依赖包括:t3:workspace(必需),用于提供支持实时重载的开发服务器,若尚未加载需立即加载。当后端在范围内时,还需加载框架/语言的约定技能,例如 Django 约定、Python 风格指南。TeaTree 会依据仓库形态自动检测相关的 ac-* 技能;若加载器未触发,需自行加载相应的编码技能,如 Python 代码加载 /ac-python,Django 项目加载 /ac-django,并且要在写任何代码之前加载,而非之后。
三、TDD 纪律 核心规则为先写会失败的测试,再写使其通过的实现。测试用于证明功能有效;若在实现之后才写测试,风险是测试的是实现而不是行为。修复缺陷时,测试必须在修复前复现该缺陷(红),然后修复(绿)。回归测试只有在被观察到在修复前代码上失败时才有效。如果测试断言的是结构上必然成立的结果,即使在有缺陷的代码上也会通过,它就是空洞的、没有守护任何东西。对于并发/状态修复尤为明显:应断言缺陷所违反的可观察契约,而不是代码路径总会产生的后置条件。在声称回归测试守护了某个修复之前,需要临时回退修复(或以其他方式重新引入缺陷),确认测试变红;如果仍然绿色,则该测试并未守护该修复。
在连接级写入串行化的后端上,红色复现必须模拟修复前代码实际的事务形态,而不是用 atomic() 包裹的近似形式。当生产后端在连接级串行化写入者时,将竞争写入者包裹在 transaction.atomic() 中会使它们串行化,导致覆盖问题无法复现,红色测试空洞通过。如果缺陷代码在没有 transaction.atomic() 包裹的情况下执行读-改-写,那么红色测试装置也必须这样做:先做陈旧读取,再做裸自动提交写入,不使用 atomic()。必须匹配缺陷真实的并发原语,否则生产后端的串行化会掩盖测试声称要钉住的竞态。
fail-safe-to-empty 原语不应被“为空则认领/授予”的调用者在没有显式依赖不可用检查的情况下消费。当某个 helper 在真实答案确实为空以及其所需依赖不可用(模块无法导入、服务下线)两种情况下都退化为中性值(空集合/字典、None、0),该中性值具有歧义。将其中的“空”解释为“可安全继续/认领”的调用者,恰好会在无法判断的情况下采取不安全操作,这与 fail-safe 相反。在安全关键的降级路径中,消费者必须自行探测依赖可用性,在无法确认时故障关闭(跳过/拒绝),而不是从歧义的空值推断安全。在认领路径中复用 fail-open 的修剪/读取原语是导致该回归的典型方式;守护测试断言降级路径采取保守分支。
在声称测试正确之前先运行它,绝不推送你尚未运行过的回归/黄金主测试(不可协商)。新写的测试在你本地运行并在同一次响应中阅读其输出之前,不算“正确”“可能正确”或“完成”。把测试推到 CI 去判断是否通过,同时报告其正确或可能正确,是被禁止的“似乎正确”声明:CI 是慢速预言机,不能替代你自己运行测试。存在权威参考时,测试是黄金主测试,必须断言参考固定的每个值,而不是抽样。在迁移较多的仓库上做窄范围运行应使用 --no-migrations --reuse-db。顺序是:写测试 → 本地运行 → 确认输出匹配权威参考(每个值)→ 然后才提交与推送。在运行之前报告“可能正确,推到 CI”属于失败。
误导性命名是缺陷,应重命名符号,而不是用注释解释。
四、工作流要点 0b. Worktree 优先:绝不编辑主克隆(不可协商)。交给你的路径可能是规范克隆,直接编辑会破坏共享工作树、阻塞其他会话,并把未评审的提交推到错误分支。在任何编码任务的第一次编辑之前,要创建独立 worktree 并使用新分支,然后 cd 进入其中;所有编辑、测试运行与提交都在 worktree 内进行。有工单上下文时使用 overlay 创建工作树;无 overlay 的快速临时修复,先手工从默认分支创建工作树,编辑在工作树存在之后。
0c. overlay 仓库代码:先加载 overlay playbook 技能(不可协商)。当你要在其中编码的仓库由 overlay 管理时,overlay 的 playbook 技能携带该仓库的 worktree/运行/测试/lint 命令、租户规则与约定,通用开发技能不够。应在接触任何代码之前自行加载 overlay 的 playbook 技能,无条件、在询问工单 URL 之前、在阅读任何 diff 之前。
0a. 范围门:跳过时发出警告。功能在编码前受益于范围界定。teatree 会话 FSM 带有范围界定阶段。在写代码之前检查工单是否经历过范围界定阶段。若是功能且跳过了范围界定,警告一次,然后继续,不要硬阻塞。缺陷修复、文档与小战术变更不需要范围界定。
-
需要工单的 overlay 检查:当活动 overlay 配置中 require_ticket = True 时,写代码前必须存在被跟踪的 issue。使用 overlay 进行工作树创建与生命周期管理。来自 /t3:retro 的变更豁免。
-
先制定计划:始终在写代码前制定计划,绝不直接跳到编码。即使被要求“快速修复”,你的下一个动作也应是计划,而不是编辑/提交/推送。两个不相关的工单绝不捆绑为一次无计划的编辑狂潮,各自应有独立计划、工作树隔离的变更。只读调查(git fetch、读文件)豁免,属于计划的一部分。验证代码库符合预期:运行 git fetch origin main 并检查工单项是否已在 main 实现、当前架构是否匹配工单假设。检查先前工作:搜索 git 历史与 PR 列表。陈旧-OPEN-issue 门:在实现 backlog 扫描中挑选的 issue 之前,证明它确实未修复。识别范围:哪些文件、模块与仓库受影响。在写新代码之前审查代码库中的既有模式。如果任务匹配 playbook,遵循 playbook 特有的模式。功能标志检查:遵循 references/multi-tenant-development.md 中的决策门。按任务规模调整计划:简单/清晰任务用短列表说明计划后立即实现;复杂/有歧义任务使用计划模式,探索代码库、写计划、提交用户批准后再编码。配置/发现类、移除或替换 CLI 参数、提取 overlay 代码到核心、在既有扫描器或不变式拥有的路径下新增文件/目录、UI 布局/多列结构等,都有相应的先决动作要求。
-
TDD 循环:红 → 实现 → 绿 → 重构。红:写捕获预期行为的测试,运行,必须失败。绿:实现最小代码使测试通过。重构:在不改变行为的前提下清理,测试保持绿色。
-
遵循约定:每个新函数都应有完整类型注解。
五、适用场景与限制 适用场景为实际的编码实现任务,尤其是采用 TDD 的项目,以及与 TeaTree 项目工作流相关的开发。限制方面,资料未提供该技能的具体收费、价格、平台支持范围或效果承诺;也未提供完整的安装命令。资料中出现的各类命令(如 t3 <overlay> workspace ticket、git worktree add 等)属于工作流示例,应保留原样,不应改写。