Coding Agent Prompt Best Practice

仓库定位

这个仓库是一套 AI 编码 Agent 的工程化驾驶方法，不是一个 Prompt 集合。核心产品是 cybernetic-systems-engineering-v2（CSE v2）— 一个基于控制论 + 系统工程 + 总体设计（GDA）的三层路由式 skill，用 2408 行结构化协议覆盖工程语义闭环、性能并发控制、遗留代码安全变更、工程远见、主动交互与审查门禁。

仓库同时提供：

• CSE v2 的全套可执行协议（15 个 reference 文件 + router + 薄入口）
• Codex CLI 的 CSV 驱动循环 prompt
• Harness Engineering 执行框架
• 跨语言重构、门禁设计、审查模板等可复用知识库
• Claude Code / Gemini CLI 的执行与审查型 prompt 模板

---

核心产品：CSE v2

cybernetic-systems-engineering-v2/ 是本仓库的核心。它把软件开发建模为闭环控制系统，用三层渐进路由加载替代了 v1 的 792 行单块文件。它是一个自包的 skillbase，不依附于任何外部 skill：

[L0] SKILL.md (139行) + router.md (59行)     ← 永远同时加载：行为协议 + Control Contract + GDA + 路由表
  │
  ├─ [L1] router 按任务信号匹配 1 个自包含协议 (~120行/个)
  │     ├── §A 工程语义闭环：事务/幂等/状态机/异常/日志
  │     ├── §B 性能与并发控制：观测基线/影响矩阵/并发归属
  │     └── §C 遗留代码安全变更：边界冻结/特征测试/扩展点
  │
  └─ [L2] 按需深读（命中 L1 后必须继续激活，不得只停留在入口）
        ├── engineering-forethought    — 工程远见：漂移识别/升级触发/预见性自检/预训练知识调用
        ├── agent-interaction-protocols — 主动交互：会话审视/预实现校准/漂移中断/残余风险追踪
        ├── review-protocol            — 审查协议：回归优先/输出分级/Harness Backlog/演进叙事审计
        ├── project-control-topology   — 控制面/数据面/状态面/复杂性转移账本/owner matrix
        ├── decision-principles        — 机制优于策略/MTTR-first/抽象审查/演进式架构
        ├── sensor-engineering         — 基线建立/去噪/schema-sensitive/无观测不优化
        ├── dynamic-control-diseases   — 采样新鲜度/去抖滞回/anti-chatter/windup
        ├── playbooks                  — 11 类实战剧本
        ├── quality-gates              — 6 反模式 + 交付格式 + 证据信赖度
        └── gda-framework              — 五维方法论 + 理论底座 + 现代映射附录

v1（cybernetic-systems-engineering/）仍然保留，适用于： 想一次通读完整理论体系的场景、不需要路由匹配的简单任务。v2 是推荐的默认入口。

---

目录总览

.
├── README.md
├── LICENSE
│
├── cybernetic-systems-engineering-v2/   ← 核心：CSE v2 三层路由式 skill
│   ├── SKILL.md                          L0 薄入口（行为协议 + 核心哲学 + Control Contract + GDA）
│   ├── router.md                         L0 路由引擎（13 任务类型匹配 + 信号自检 4 问）
│   ├── agents/openai.yaml                skill 元数据
│   ├── assets/quickstart.md             快速上手（路由式一句话入口）
│   └── references/                      15 个协议/参考文件
│
├── cybernetic-systems-engineering/       CSE v1（单块 skill，保留作为理论参考）
│   ├── SKILL.md                          792 行完整理论论述
│   ├── agents/openai.yaml
│   ├── assets/quickstart.md
│   ├── scripts/issues.csv               v1 迭代记录（CSE-001 ~ CSE-019）
│   └── references/
│       ├── gda-framework.md              GDA 五维方法论
│       └── README.md
│
├── harness-engineering/                  Harness-first 执行 skill
│   ├── SKILL.md                          先定义成功边界 → 逐层放权 → 自主探索
│   ├── agents/openai.yaml
│   └── references/harness-engineering-digest.md
│
├── codex-auto-prompt/                    Codex CLI CSV 驱动开发
│   ├── prompt/
│   │   ├── prompt.md                    读取 issues.csv → 开发-测试-提交循环
│   │   └── doc.md                       CSV 结构说明 + 避坑点
│   └── seed-Agentsmd/
│       └── AGENTS.md                    通用 AGENTS.md 种子模板
│
└── documents/                            知识库与 Prompt 模板
    ├── claude-cn.md / claude-en.md       执行型 Prompt（身份/准则/工具/SOP/规范）
    ├── gemini-cn.md / gemini-en.md       顾问型 Prompt（审查/反馈/禁止直接写代码）
    ├── 从 SWE-CI 到 Harness Engineering.md  SWE-CI 论文解读 + 共性技巧 + 审查 Prompt 模板
    ├── cross_language_refactor_reusable_kb.md  跨语言重构知识库（流程/验收/CI/人机协作）
    └── cc的最佳用法.md                   Claude Code 三条实战心法

---

文件导航

cybernetic-systems-engineering-v2/ — 核心 skill

cybernetic-systems-engineering/ — CSE v1（保留参考）

harness-engineering/ — 执行框架 skill

codex-auto-prompt/ — Codex CLI 驱动

documents/ — 知识库与 Prompt 模板

---

怎么选用

按"我当前的任务"选

按"我想深入学习系统论"选

1. cybernetic-systems-engineering-v2/SKILL.md — 核心哲学与行为协议
2. cybernetic-systems-engineering-v2/references/gda-framework.md — 五维方法论与四步法
3. cybernetic-systems-engineering/SKILL.md — v1 的完整理论论述（可选，用于完整学术理解）
4. cybernetic-systems-engineering/scripts/issues.csv — 理解整个体系的迭代演化过程

---

v1 → v2 演化路径

v1 适合需要完整理论理解的场景。v2 适合实际工程使用——它把理论收束为可执行协议，并根据任务信号自动匹配。

---

仓库最适合的场景

• 将 Codex/Claude 等编码 Agent 放入复杂工程任务，用 CSE v2 做系统性控制
• 构建 Agent 的主动交互能力（不等用户报错，自己发现并报告漂移、约束缺口、残余风险）
• 自动化代码审查（回归优先、证据驱动、Harness Backlog 产出）
• Codex CLI 的 CSV 驱动长时间自动开发与自审
• Claude Code 与 Gemini CLI 的分工协作（执行 vs. 审查）
• 需要 harness-first 执行框架的复杂排障或 CI 修复
• 跨语言重构方法论的落地参照