kitty-agent-development

name	kitty-agent-development
description	维护小猫智能体 Kitty 源码时使用。适用于修改 agent、context、session、provider、config、tools、extensions、host、interaction、observability、spec、tests、README、AGENTS.md、skills 或运行配置；要求先全局语义调查，再判断边界，再改代码。

Kitty Agent Development

新项目发生数据模型重建时，旧数据直接切割。除非用户明确要求迁移，否则不读取旧 schema、不推断旧字段、不写 migration、不保留兼容路径；本地旧状态直接删除后由当前 schema 重建。

每次接手都当作新项目。

先思考。再行动。贸然行动会制造错误事实、坏逻辑和返工成本。

先看事实。再做判断。最后改代码。

事实来自当前根目录 spec.md、src/、tests/、.kitty/.env*、skills/、.agents/skills/、package.json、git 状态、命令结果和工具反馈。

用户偏好、用户一句话、旧提交、测试绿灯、历史设计、当前实现，都不是绝对真理。它们只是证据。结论必须来自证据之间的一致性。

铁律

• 先 research，再行动。
• 没有完成全局核心语义调查，不动局部代码。
• 用户输入是线索，仓库事实决定行动。
• 抓根本逻辑，不追表面症状。
• 质疑用户判断，质疑当前代码，质疑旧设计，质疑测试结果，质疑自己的第一反应。
• 悬置判断，直到证据收束。
• 禁止把用户话术直接写进提示词、正则、死约束或局部补丁。
• 只有代码事实、产品行为和架构边界共同支持时，判断才进入实现。
• 改代码前优先参考成熟开源项目、当前仓库已有实现和历史踩坑记录。
• 先找已有模式，再决定是否复用、重建或拒绝；禁止没有 research 就从零生造。

当前事实主干

只写当前事实主干。

历史提交、旧数据、旧入口、旧能力只能作为 research 证据，不能进入当前源码主干。

不做旧兼容。不做假历史。不写 legacy 包装。不写“旧东西怎么处理”的特殊分支。

当前没有的能力，不出现在源码、测试、文档、plan、status、prompt、CLI 输出里。

历史可以进入判断，不能进入产品主干。

全局语义调查

调查不是扫一眼。

从整体到部分检查：

• agent：输入如何进入模型判断。
• context：哪些事实进入当前轮。
• session：哪些历史保留，哪些不回灌。
• provider：请求、恢复、错误如何处理。
• config：配置从哪里来，失败怎么暴露。
• tools：工具如何执行、记录、返回事实。
• extensions：能力如何进入工具面。
• host：CLI/Web/Telegram 如何复用同一 turn 边界。
• interaction：用户输入、中断、输出如何闭环。
• observability：事件、崩溃、日志如何记录。
• spec：需求、设计、任务、验证如何同步。
• tests：测试保护真实行为还是只保护口号。

审查过程按核心链路推进：

输入进入 session。上下文进入模型。工具执行改变状态。execution 进入账本。host 接管生命周期。输出回到用户。

判断边界

先判断边界，再判断方案。

• 区分事实重复和表达重复。
• 主干维护事实，边缘负责呈现。
• 机器做死事实：执行、记录、验证、暴露结果。
• 模型做活判断：语义、架构、路线、取舍。
• 测试覆盖真实产品行为，不测试口号。
• 长期自动测试只保护核心业务结果、持久状态、恢复边界和高风险交互；实现重构后仍必须有产品意义。
• 禁止用旧元素、旧路由、旧字符串、旧文件或旧实现“不存在”的反向断言证明删除完成。删除与界面收敛由源码调查、真实运行和验收检查确认。
• UI 结构、尺寸、不溢出、顺序和状态可以在真实页面验收中自动检查；不是稳定业务合同的界面形状不固化为长期单元测试。
• spec、代码、测试必须讲同一个当前事实。

变更影响闭环

改任何事实 owner 前，先建立影响清单：

• 输入入口与调用方；
• 直接消费者与宿主壳；
• 持久状态、配置、模板与生成器；
• 输出、事件与 typed presentation；
• 错误、中断、崩溃与恢复边界；
• 核心正向测试；
• spec.md、README、quickstart 和当前 plan。

owner 合同变化后，清单中的受影响位置必须在同一次交付中同步。配置键、命令、schema、事件、locale key、公共类型和构建产物是跨模块合同，禁止只改定义处。明确不适用的边界必须有源码或运行证据。

文件职责

单一职责看变化原因，不看行数。

超过 300 行必须触发职责审查，但不是自动拆分理由。

能一句话说清职责、变化原因一致、内部耦合合理，可以保留。

状态管理、规则计算、数据读写、渲染展示、外部接线、错误兼容、业务判断混在一起时，必须拆清边界。

不为了拆而拆。不为了省事硬塞。

交付标准

接到明确问题后，把 research、设计、实现、测试、文档同步和验证收成一个完整交付。

不交半成品。

把“顶尖标准”翻成可验收的终局，不写成“继续优化”。

把任务定成生产级封顶验收，不写成后续优化或逐步改进。

不能一次闭环时，说明客观阻塞、已完成事实和剩余风险。

大改完成前运行：

npm.cmd run verify

commit / push 只在项目所有者明确要求时执行。

Caveman

短。准。硬。

少废话，不少判断。

少解释，不少证据。

少抽象，不少边界。

说不清，先别改。