.codebuddy/ 框架总览

本目录是 CodeBuddy Agent 在本项目中的行为规范和可复用能力包。任何 AI Agent 或人类开发者接手本项目前，先读本文。

.codebuddy/
├── README.md              # 本文件：总览与导航
├── rules/                 # 规则（强制性约束）—— 开发者 / Agent 执行层
│   ├── *.md              # 9 份规则，详见下表
│   └── .archived/
│       ├── feedback/     # 使用框架过程中发现的问题与改进记录
│       └── README.md     # 归档说明
├── skills/                # 技能（可复用工作流）—— 开发者 / Agent 执行层
│   └── */SKILL.md        # 9 个 skill，详见下表
└── governance/            # 治理层 —— Leader / workshop 负责人视角
    ├── README.md                  # 治理层导航
    ├── delivery-lifecycle.md      # 交付流程契约（流程通用性）
    ├── quality-dashboard.md       # 质量仪表盘（质量维度）
    ├── retrospective-sop.md       # 复盘 SOP（经验沉淀）
    ├── architecture-fitness.md    # 架构健康度（技术先进性）
    └── tooling-landscape.md       # 管理工具全景（管理工具协同）

三层分工：

上层不重复下层内容，只做导航和抽象；下层变更不引起上层级联修改。

Rules 是强制性约束。Agent 在本项目内工作时必须遵守。

Skills 是可按需加载的工作流模板。通过 use_skill 工具调用。

详细元数据与依赖图见 skills/SKILLS.md（v2 Agent Harness 规格）；规格定义见 skills/_AGENT_HARNESS_SPEC.md。

关键字段（每个 skill 的 _meta.json 都含）：

• triggers — 关键词 + 上下文触发规则
• dependencies — 依赖的其他 skills / rules / 外部工具
• inputs / outputs — 机器可读的输入输出契约
• side_effects — 五维副作用分类（fs / net / db / git / external-api）
• idempotent / requires_confirmation — 幂等性与用户确认要求
• cost — 成本预估（时长、LLM 调用数、复杂度）

"静态检查通过 ≠ 代码能运行"。任何交付必须跑通真实编译（mvn compile / tsc --noEmit），不允许仅凭 read_lints 0 错误、括号平衡通过来断言代码正确。工具链版本不匹配时用容器锁死项目目标版本。

代码评审前必须已通过：

• 源码真实编译
• 测试代码编译
• 至少 1 个上下文加载测试（@SpringBootTest 或等效）

从 <PM-Tool> 拿到需求后必须：

1. 需求扩写（R1）
2. 需求分析（最小必要原则）
3. Git 分支切换
4. 开发 + 测试
5. Phase 4.0 真实编译验证 → 4.1 运行测试
6. 代码就绪通知 → 等待确认 → 推送远端

在使用本框架过程中发现的问题（规则漏洞、skill 缺陷、工具盲区）记录在 .archived/feedback/FB-XX-*.md，每条 FB 有明确的"来源 / 触发条件 / 建议修复 / 状态"。RESOLVED 的 FB 保留作为历史案例追溯；OPEN 的是下一轮迭代的待办输入。完整的复盘触发时机与闭环机制见 governance/retrospective-sop.md。