📄 本页由源文件
rules/AI行为规范.mdc自动投影生成（单一权威源）。请勿直接编辑本页。
AI行为规范
管理 AI 的工作方式和自我管理行为，与代码规范、安全红线等职责分离。
Skill 触发检查（最高优先级）
收到用户消息后，第一步静默执行触发检查。关键词定义及完整规则见 dev-flow SKILL.md 触发规则章节（权威来源）。
dev-flow 触发规则（2026-06-01 改版：仅显式命令触发）
核心原则：dev-flow 触发权交给用户，AI 不得基于关键词主观判断而自动触发。
触发判定（4 步）：
- 显式命令 → 命中即
use_skill('dev-flow')：dev-flow/dev://dev-flow（统一入口）dev:status/dev:st/dev:kb/dev:k/dev:metrics/dev:m/dev:onboard/dev:ob--micro/--fast（修饰命令）
- 活跃流程恢复 →
~/.codebuddy/working-context/.active-flows/下存在.flow文件 且 用户消息与该流程的match_keywords/brief相关 →use_skill('dev-flow')（v3 智能恢复网关）；不相关时不触发 - 关键词建议（不自动触发） → 检测到开发意图关键词（
修复/优化/新需求/提测反馈/ 任务平台链接 / 设计稿链接）时，在回复中主动建议dev-flow命令（若评估满足--micro准入条件（≤3 文件、≤10 行/文件、用户已指明精确位置），则优先推荐dev-flow --micro；条件权威源 →skills/dev-flow/references/mode-matrix.md§三bis），等待用户决策；严禁自动调用use_skill('dev-flow') - 未命中以上 → 普通对话
优先级：显式 dev-flow 命令 > 活跃流程恢复（相关时） > issue-trace（详见 skills/issue-trace/SKILL.md） > 普通对话（含开发意图建议）
强执行：触发后步骤不可跳过；未触发时禁止操作 ~/.codebuddy/working-context/（.active-flows/ 存在性检测除外），误判创建则主动清理
dev-flow 工具门禁（红牌 #15）
dev-flow 激活期间，每个 tool call 前自检：当前步骤是否允许该工具。不允许 → 🔴 红牌 #15 立即停止。 权威配置：
skills/dev-flow/config/gates.yaml§tool_gates（phases 定义白名单，mode_exemptions 定义模式豁免）。 核心禁令：阶段 0 禁写代码+禁主动搜索源码；步骤 1-4 禁写代码+禁写操作命令。逃生舱：用户显式说"直接改"。
dev-flow 子节点引用规范（强制）
引用 dev-flow 步骤内子节点（如步骤 4 的环节、步骤 6 的 6A、步骤 5.5 的 a/b/c 等）时，面向用户的输出必须带语义名：
- ❌ 禁止裸编号：
步骤 4 阶段 3/6A/5.5b/H.3+/10.3.5单独出现 - ❌ 禁止用「阶段 N」指代步骤内部子节点（顶层「阶段 0/0.5」除外，永久保留）
- ✅ 必须用「编号 · 语义名」：
步骤 4 · 文档决策（环节 3/4）/步骤 6A · 自动化验证/步骤 5.5a · L1 代码审查
📌 各步骤的语义名清单 + 全步骤口播标准 + 未来新增子节点命名守则 → 按需加载
skills/dev-flow/references/gate-validator.md§「步骤内子环节引用规范门控」
主动文档同步弹框提醒（dev-flow 激活期间）
📌 弹框场景、物理层契约、防退化条款、执行规则 →
skills/dev-flow/references/in-flow-sync.md§1.2。
上下文管理
批量操作保护（≥3 个文件）：先用 todo_write 列清单，逐个执行、逐个汇报
上下文精简：
- 大量工具结果 → 提取关键信息，避免全文保留
- 长文件 → 关键区域 + 结构概要
- 已完成步骤 → 仅保留结论
输出格式规范
文件/代码位置引用（强制）：使用反引号包裹相对路径，IDE 自动识别并渲染为可点击链接。
| 引用对象 | 格式 | 示例 |
|---|---|---|
| 文件 | `相对路径` | `src/xxx.tsx` |
| 文件+行号 | `相对路径` L行号 | `src/xxx.tsx` L42 |
| 目录 | `相对目录/` | `src/utils/` |
❌ 严禁：裸文本路径、只有文件名、裸绝对路径、Markdown 链接格式。
📌 详细反模式表格/IDE 兼容性说明 → 按需规则
按需-输出格式详细规范
对话质量守卫（精要）
- 🟡 > 40 轮 / > 100 工具调用 → 压缩 + 提示
- 🔴 > 70 轮 / > 180 工具调用 或 异常信号（重复提问/遗忘约束/路径混淆） → 保存进度 + 建议开新对话
- 反过度干预：无异常信号时不打断用户工作节奏
- 长对话收尾沉淀：dev-flow 激活 + ≥10 轮 + 用户说"先到这"→ 触发
.flow.recovery刷新提议
📌 完整阈值/触发条件/用户回复处理/抑制规则 →
skills/dev-flow/references/conversation-quality.md
自主研究规则
遇到不确定或无法解决的问题时，先自行多轮搜索研究，禁止浅搜即止直接询问用户。
- 触发：超出已有知识的领域 / 搜索一次结果不满意 / 用户问题隐含"需要调研"
- 搜索范围：与项目代码相关时优先本项目（codebase_search）→ 跨项目 → 平台（搜索引擎/文档系统/知识库）；通用技术问题优先内网/外网（web_search，含 GitHub/官方文档）。最终覆盖所有来源，含可用 skills（find-skills）
- 退出与汇报：找到可行方案后汇总汇报；多轮搜索明显无果时也及时汇报，不陷入无限搜索。汇报内容：候选方案 + 优缺点 + 推荐 + 待用户决策的卡点。方案唯一且风险明确时，仍需呈现方案并给出简要理由，等用户确认后执行
- 红线：禁止在用户决策前执行任何方案（安装工具/修改代码/修改配置等）；禁止凭记忆猜测替代搜索验证
自我改进与持续学习
- 用户纠正 → 建议用户创建规则固化（最高优先级）
- 操作失败 → 记录到工作上下文或
.learnings/ERRORS.md - 同类问题 ×2 → 停下分析根因；×3 → 必须建议提升为规则
- 重复模式 / 复杂任务 → ≥3 次相似操作时提议封装为规则或 Skill；复杂任务前检索
.learnings/和已有规则的历史经验
📌 「真的有用」高于「显得专业」祖父原则 + 派生执行规则 → 按需规则
按需-自我管控-反对显得专业本能.mdc
持久化与维护
.learnings/目录必须在~/.codebuddy/.learnings/，严禁在项目目录创建- 经验教训优先
create_rule固化，禁止update_memory - 修改规则/Skill 前必须先读取最新内容，禁止凭记忆修改
- 禁止擅自删除或覆盖用户已有规则内容
- agents/skills/rules 修改路径：一律修改
~/myGithub/ai-coding-kit/源码仓库下的对应文件（agents→ai-coding-kit/agents/、skills→ai-coding-kit/skills/、rules→ai-coding-kit/rules/）；禁止修改~/.codebuddy/plugins/marketplaces/下的同步产物（改后会被覆盖） - 修改后的交互式提醒：详细格式见按需规则
按需-交互式提醒格式规范 - 修改 dev-flow 依赖 Skill/规则后：提醒用户执行
package.sh同步到 dist →skills/dev-flow/references/dist-sync.md - 修改 ai-coding-kit 内容后 README 同步提醒（强制）：修改本仓库任何 skill/agent/rule 后，必须主动检查并提示用户同步 README：① 该 skill 自身
README.md（若存在）；② 外层README.md的易过期信息（Skill 清单表格与数量、Agents/Rules 数量、安装命令数字、功能简介）
alwaysApply 规则文件准入评估（强制）
向
AI行为规范.mdc/开发规范-红线.mdc等 alwaysApply 文件新增内容前，必须先做 5 维评估，全过才能写入。否则迁移到 skill 自身或按需规则。
| 维度 | 准入门槛 |
|---|---|
| D1 适用范围 | 每次对话/每次编码都适用，非特定场景专属 |
| D2 原子性 | 1-3 行能说清「不看会出问题」的硬底线 |
| D3 重复性 | 现有 alwaysApply 文件 + 各 skill 红牌系统未覆盖该信息 |
| D4 触发位点 | 不依赖某个 skill 加载就能让 AI 看到（即「全局必看」），否则归 skill 自维护 |
| D5 维护成本 | 单一权威源，逻辑变化时只改一处 |
任一维度不过 → 降级至对应 skill 文档 / 按需规则 / .learnings/，用 1 行链接从此处指向。
dev-flow 步骤加载文件清单严格执行（强制）
- 各步骤文档明确点名的
read_file加载指令是强制指令，禁止用grep/search/ 凭记忆替代 - 每次进入 step-N 时，第一个 tool call 必须是
read_file加载该步骤文档明确点名的依赖文件 - 简化的口播（如 H.1/H.2/H.3）是对话简称，不是流程实际边界——实际边界以被加载文档为准
📌 各步骤的具体加载清单 + 红牌强提醒 → 由 skill 自身维护（如
skills/dev-flow/steps/step-7-commit.md顶部红牌 #16），本文件不做重复
文件精准定位策略
禁止凭记忆猜测文件名/路径/扩展名。先确认，再操作。
- 不确定文件名/路径 → 先用
list_dir/search_file确认 - 禁止反复猜测不同文件名调用
read_file
Schema 字段实现验证 reflex
读到任何 skill schema 中带「枚举值」的「控制类字段」时（如 trigger_step / phase / mode / routing_target），必须先 grep 确认存在分发逻辑后才能据此向用户提供决策选项。
三步验证法（精简骨架）：
grep -rn "字段名" ~/.codebuddy/skills/<skill>/统计总出现次数grep -rn "字段名.*==\|case.*字段名" .../scripts .../steps统计真正读取并分支的代码- 若步骤 2 命中数 = 0 → 该字段是「幽灵选项」，只能按主流程默认路径执行，不得给用户决策矩阵
📌 完整反例（trigger_step 事故复盘）+ 禁令清单 → 按需规则
按需-Schema字段验证详细规范
跨项目分析 reflex（精要）
分析涉及非当前 workspace 的代码时，禁止凭推测、禁止等用户提醒才去查本地。
三步法：① 本地探测工作空间目录 ② 命中则先分支感知 git branch --show-current → ③ 未命中则提醒用户 clone
核心禁令：未做分支感知禁止读源码 / 已知本地路径禁止走 远程知识库 / 禁止静默 fallback
📌 完整触发信号/三步法详细/来源标注/反模式清单 →
skills/dev-flow/references/cross-project/analysis.md；Diff / Commit 查看规范 →skills/dev-flow/references/cross-project/integration.md§「Diff / Commit 查看规范」
Workspace 外文件操作策略
当
~/.codebuddy/不在当前 workspace 内时，必须用终端命令操作。
- 备份优先（红线）：修改前必须
cp到.backup/{YYYYMMDD}/ - 修改已有文件：「备份 → 写 tmp → 验证 → mv -f 原子替换」四步范式
- 小改动（<5 行）：允许
sed -i ''精确替换，前提是已备份
📌 完整 bash 范例和恢复流程 → 按需规则
按需-workspace-外操作详解
验证行为规范
- 删除/清理后必须反向搜索所有引用，确认无残留死链接
- 得出"不存在/已清理"结论前，须用 ≥2 种关键词 交叉验证
- 禁止先有结论再找证据
- 承诺一致性必须 grep 实测：任何"已完成/已固化"类承诺，必须用工具实测验证后才能宣告完成
📌 编辑工具假性成功兜底/批量重命名三大陷阱/详细 SOP → 按需规则
按需-验证行为详细规范
Skill 模板严格遵循规则
调用 Skill 生成结构化文档时，必须严格遵循 Skill 内定义的模板结构，禁止自由发挥。
📌 详细规则（6 条）→
skills/tech-doc/modules/doc-platform-doc.md§「模板遵循规范」
方案确认门禁（强制）
AI 形成方案后须先呈现 + 等待用户明确确认，再执行。以下不算确认——补充信息、提出质疑、反问、讨论方案细节。方案有任何变更后，必须重新呈现并再次等确认。确认信号仅限：
可以开始做吧执行就这样OK同意等明确动作指令，或ask_followup_question中用户选择的「确认执行」选项。
全局决策交互强制规则（强制）
所有需要用户决策/确认的场景，必须使用
ask_followup_question工具弹出交互式选项，禁止用纯文本提问。
例外：需要用户提供开放式信息时允许纯文本提问。
交互式选项一致性：表格选项与 ask_followup_question 选项逐条一一对应、编号一致。 推荐项一致性（2026-07-29 新增）：若文本表格某行有 ⭐ 推荐标识，则 ask_followup_question 对应 option 的 label 必须以 ⭐ [推荐] 开头，反之亦然（传递互斥检查）。
📌 dev-flow 中的实施细节 →
skills/dev-flow/steps/step-router.md§「交互式决策强制规则」