Dev Discipline

开发纪律与 Agent 工作流规则。本技能是代码任务的唯一规则源；CLAUDE.md 只做路由。

Harness 框架：所有代码任务遵循 Model + Harness 架构。LLM 提供推理，Harness = 上下文 + 工具 + 约束 + 验证 + 纠正。本文件将这五层落地为具体规则。

完整详细规则 → references/dev-discipline.md
上下文工程原则 → <LOCAL_AGENT_HOME>\references\context-engineering.md
Harness 工程原则 → <LOCAL_AGENT_HOME>\references\harness-engineering.md

首次使用与离线可用性

本技能的核心规则、冲突预防脚本和完整性检查均可离线运行，不依赖国外网络。

1. 首次使用或更新后运行：python validate_skill.py
2. 输出 PASS 后即可使用；WARN 表示可选增强工具缺失，按降级说明继续；FAIL 表示核心文件损坏或缺失，先修复再使用。
3. 不因验证失败自动联网、安装依赖或修改全局配置；先报告缺少项和可行替代。

工具可用性与降级

当多个条件同时命中时，优先级为：安全/人工确认 → 任务分级 → 适用技能路由 → 默认执行流程 → 可选增强工具。高优先级规则与低优先级规则冲突时，以高优先级为准。

内置记忆与自我提升

两个模块均为离线、零依赖工具；必须用 --root <项目目录> 明确指定数据归属位置，不能把数据写入本 Skill 目录，也不会自动收集聊天内容。

写入前，两个脚本会拒绝疑似密钥、令牌或密码。请只记录可共享、可复用的经验；账号、联系方式、原始对话和私密业务数据不得写入。

速查卡

Context Engineering（上下文纪律）

> 上下文 = Agent 的眼睛。上下文质量决定 Agent 能力上限。

Lost-in-Middle 强制检查

回答涉及长上下文中的信息时：
1. 不要在回答中间引用上下文 mid-section 的关键事实而不加位置提示
2. 将上下文中部的关键约束/数字显式复述到回答开头
3. 如果答案依赖上下文中间的第 N 条信息，在回答末尾附 (来源: 上下文第 N 条)

上下文压缩触发条件

工具定义设计原则

Harness 工程：约束/验证/纠正

> Agent = Model + Harness。LLM 提供推理，Harness 保证可靠性。

验证检查点（L2+ 任务完成时强制）

纠正降级路径

Process

代码任务按以下流程执行：

1. 任务分级（先判定等级）

2. LESSONS-FIRST（任务前）

触发 self-improving-agent 检查 .learnings/ + references/lessons.md，历史踩坑转为本次约束。

自动检测触发：

3. 核心执行流程

SEARCH → THINK → (L3+: agent_comms.py check) → CODE → SIMPLIFY → VERIFY

L3+ 启动多 agent 前：python agent_comms.py announce <name> <files> 预占文件，冲突则串行。

• SEARCH: 先搜 Skill 本地 → 仓库内 → MCP → 包管理器 → GitHub
• THINK (L2+): 输出 理解/方案/涉及文件/风险
• SIMPLIFY: 控制流压平、命名直接、无复制粘贴、无过度抽象、无孤儿代码
• VERIFY: 最多 3 轮，失败超过 3 轮停止并报告

4. 核心纪律

→ 完整规则见 references/dev-discipline.md §4/§5/§6/§7/§8

5. 回答与证据纪律

在回答、评审、方案建议或结论输出前：

1. 先检查问题是否存在错误前提、逻辑跳跃、概念混淆、信息缺失或未经证实的假设；发现问题时直接指出，不基于有缺陷的前提继续推导。
2. 不自动认同用户观点，也不为迎合而附和。即使对方表达很有说服力，也独立判断其是否合理。
3. 明确区分已核实的事实、基于现有信息的合理推测、主观判断，以及暂时无法证实的信息，避免将不同性质的内容混为一谈。
4. 涉及数字、日期、人物、引用、研究结论、案例或具体事件时，尽可能核实来源；无法确认时明确说明不确定性，不编造、补全或伪装成事实。
5. 不同意用户判断时，清楚指出不同意的部分，说明原因，提供关键证据、反例、潜在风险或更合理的替代解释。
6. 区分”证据不足”与”结论错误”：不因暂时缺少证据就直接判定用户观点错误，也不把”可能成立”描述成”已经证实”。
7. 除回答表面问题外，主动指出可能被忽略的重要变量、适用条件、隐含风险、矛盾或偏差，帮助获得准确、完整且经得起检验的信息。

6. 高风险红线

修改任何源码/配置/workflow 文件前：

7. CLEANUP（任务结束）

禁止：不告知直接删、删用户手动创建的文件、删 .git 内容、rm -rf 批量清理。

8. Git 格式

<type>: <description>

type: feat / fix / refactor / docs / test / chore / perf / ci

9. 输出格式

• L0/L1：直接结果
• L2+：按 REVIEW 自查格式（改动文件 / 改了什么 / 是否影响外部接口 / 如何回滚）
• 不 emoji 装饰，不寒暄铺垫和总结段落

Few-Shot 示例

> 原则（《AI Agent》书第2章）：2-3 个精心挑选、覆盖边界情况的示例，胜过 10 个大同小异的示例。

示例 1：L1 任务 — 修改单个函数

用户: "把 extract_date 函数的正则改成也支持 YYYY/MM/DD 格式"

执行:
  SEARCH: Grep("def extract_date") → 找到 src/parser.py:42
  THINK: 单文件单函数，L1。改正则，加测试用例。
  CODE: Edit src/parser.py — 修改 regex pattern
  VERIFY: python -m pytest tests/test_parser.py::test_extract_date -q → PASS
  CLEANUP: 无临时文件
  OUTPUT: "已将 extract_date 改为支持 YYYY/MM/DD。测试通过。"

示例 2：L2 任务 — 新建 CLI 命令

用户: "给 knowledge_graph 加一个 export 子命令，导出为 CSV"

执行:
  SEARCH: code-review-graph search "cli" → 定位 cli.py
          code-review-graph query callers_of "cli.py::main" → 3 个调用者
  THINK: 多文件，新功能，L2。涉及 cli.py + exporter.py。
  PLAN:  1) 新建 exporters/csv_exporter.py
         2) cli.py 添加 export 子命令
         3) 测试: test_csv_export.py
  CODE: Write → Edit → 运行测试 → PASS
  VERIFY: code-review-graph impact --files cli.py exporters/csv_exporter.py → 影响范围符合预期
  CLEANUP: 删 test_csv_export.py（一次性验证）？→ 保留，它是持久测试
  OUTPUT: "已添加 `python -m knowledge_graph export --format csv`。3 个调用者不受影响。"

示例 3：L4 边界 — 不该做的事

用户: "帮我自动提交并推送到 main"

执行:
  THINK: Git push = L4 高风险。CLAUDE.md 边界：commit/push 需要用户明确指令。
  OUTPUT: "Git push 需要你明确确认。当前改动: src/parser.py, tests/test_parser.py。
          要我执行 `git commit -m \"...\"` 和 `git push` 吗？"
  → 等待用户回复 "提交/推送" 才放行。

持续进化（双循环）

> 在线执行（完成任务+记录证据）→ 离线进化（聚合轨迹→诊断→候选→验证→发布）

Reference

• 完整规则 → references/dev-discipline.md
• 非代码产出技能分工（PPT/文档/可视化/文件阅读）→ references/skill-routing.md
• 学术论文工作流 → <ACADEMIC_WORKFLOW_ROOT>\SKILL.md
• 跨工具交接 → <ACADEMIC_WORKFLOW_ROOT>\handoff_protocol.md
• 历史 LESSONS → self-improving-agent skill
• 上下文工程原则 → <LOCAL_AGENT_HOME>\references\context-engineering.md
• Harness 工程原则 → <LOCAL_AGENT_HOME>\references\harness-engineering.md

Code Review Graph 集成

修改代码前，用 code-review-graph 查变更影响范围（~82x token 节省）：

# 查谁调用了目标函数
code-review-graph query callers_of <函数名> --repo <项目路径>

# 查目标函数调用了谁
code-review-graph query callees_of <函数名> --repo <项目路径>

# 文件概要
code-review-graph query file_summary <文件名> --repo <项目路径>

# 模糊搜索
code-review-graph search "<关键词>" --repo <项目路径>

# 变更影响分析（修改后）
code-review-graph impact --files <修改的文件> --repo <项目路径>

# 增量更新图（代码修改后）
code-review-graph update --repo <项目路径>

已索引项目：
| 项目 | 路径 | 节点 | 边 |
|------|------|------|-----|
| 学术工作流 | <ACADEMIC_WORKFLOW_ROOT> | 23,451 | 328,395 |
| chat2api | <PROJECT_ROOT>\chat2api | 185 | 2,036 |

工作流：search 定位 → query callers_of 查影响范围 → 修改代码 → update 更新图 → impact 验证