Code Bagu：一个让 AI 写代码少改 10 遍 bug 的结构化注释协议

给 AI 代码生成套上"八股文"框架：破题 → 承题 → 起讲 → 入手 → 起股 → 中股 → 后股 → 束股。AI 先出框架（仅注释），你检查结构完整性，再填实现。效果：bug 迭代从 15 遍降到 3~5 遍。

---

为什么需要这个

跟 AI 说"帮我写个限流器"，它给你写了一个。你跑一下，"嗯，能跑"。但第 144 行有个 remaining 计算可能是负数，你根本不知道。

你用 GPT-4 对吧？1M context 烧不起。你改用 DeepSeek 和 Kimi 对吧？便宜是便宜，但输出经常不够严谨。

Code Bagu 解决的就是：怎么用便宜的国产模型，产出靠谱的代码。

---

核心设计

三层递归结构

文件级  拓扑图头     — 10秒理解模块全貌
  ↓
函数级  八股段落     — 100%可预测的注释位置
  ↓
块级    对偶标记     — 静态检查完整性

八股段落规范

# 破题：获取用户订单列表；不做分页逻辑和权限校验。
# 承题：依赖 order_db、user_context。前置：user_id 已认证。
# [起讲] 从数据库查询 → 组装响应 → 返回列表
# 入手：获取数据库连接（事务内）
def get_orders(user_id):
    # ==== 起股 ====
    # 取：user_id (int)
    # 验：user_id > 0，否则 raise ValueError
    
    # ==== 中股 ====
    # 算：SELECT * FROM orders WHERE user_id = ?
    # 转：Row → OrderResponse schema
    
    # ==== 后股 ====
    # ✓ 正路径：有订单 → 返回 OrderListResponse
    # ✗ 降级路径：无订单 → 返回空列表；DB超时 → raise TimeoutError
    
    # ==== 束股 ====
    # 给出：OrderListResponse(items=[...], total=N)
    # 留下：归还数据库连接到连接池

对偶标记系统

标记	含义	AI 检查逻辑
✓ / ✗	正路径 / 降级路径	统计 ✓ 和 ✗ 数量是否相等
🔒 / 🔓	资源申请 / 释放	统计 🔒 和 🔓 数量是否相等
↗ / ↘	计数器增 / 减	检验增减平衡性

---

工具链：DeepSeek + Kimi Code

你说需求（人话）
    ↓
DeepSeek 预处理 → 拆成"做什么/不做什么/边界条件"
    ↓
Kimi Code → 按八股规范先出框架 → 你检查 → 再填代码

• DeepSeek：1M context 几块钱，做需求拆解
• Kimi：200K context，装下整个项目 + 八股规范
• 八股约束：弥补模型输出不稳定

---

真实案例：2.6 万行项目实战

用这套方法做了一个智慧体育训练系统（RK3588 ARM 板载）：

• 94 个 Python 文件，26,588 行代码
• 6 种运动动作实时识别（跳绳、开合跳、高抬腿、深蹲、仰卧起坐、俯卧撑）
• FastAPI + WebSocket 后端，Qt QML 前端
• 全部由 AI 生成

代码审查发现 59 个 bugs，定位耗时：

搜索目标	传统方式	八股方式
异常处理在哪	grep except，约30s	grep "==== 后股 ===="，约5s
资源泄漏检查	手动追踪所有 lock/acquire	检查束股"留下"字段

---

快速开始

git clone https://github.com/linyy750911/bagu-coding

把 code_bagu_skill.md 粘贴到 Kimi Code 的 Skill 设置，根目录放 AGENTS.md。

给 AI 的指令："不要写实现。先按八股规范输出完整框架。"

---

项目地址

GitHub: github.com/linyy750911…

MIT License，随便用。