# AI Agent 开发知识库 v1

## Purpose
为内部团队提供一套可执行的 `Handbook + SOP`。本知识库把当前目录的 5 个源资产压缩成统一入口，覆盖 `CC Switch` 多 agent 编排、Spec 驱动开发、模型路由、阶段流程、模板和 ADR。

## When to Use
- 新项目要从标准脚手架和标准流程启动时
- 维护项目要补齐 `SPECS/`、补做 Alignment、补做质量收敛时
- 团队需要统一 `GPT-5.4 Pro xhigh`、`Claude Opus 4.6` 和 `CC Switch` 的分工方式时
- 新成员需要在不回看原始会议纪要的前提下上手执行时

## Inputs
- 根目录下的 3 份会议整理文档
- `workflow.zip`
- `skills.zip`
- 当前项目的会议纪要、参考仓库、业务需求、现有代码库

## Outputs
- 一套可导航的知识库结构
- 7 阶段执行流程
- 3 条主 playbook
- 可复用模板
- 带日期的策略 ADR

## Primary Agent/Model
`CC Switch` 主控线程，默认主推理模型为 `GPT-5.4 Pro xhigh`

## Secondary Agent/Model
`Claude Opus 4.6`，用于长文档消化、Spec 审读、第二视角复核

## Required Skills
- `ralphy-initializing`
- `spec-tasking`
- `spec-reviewing`
- `spec-gap-tasking`
- `tdd-planning`
- `tdd-implementing`
- `code-simplifying`
- `code-refactoring`
- `architecture-audit`

## Steps
1. 从 [`sources/README.md`](./sources/README.md) 确认规则来源和冲突取舍。
2. 从 [`playbooks/`](./playbooks/) 选择最贴近当前项目的执行路径。
3. 按 [`workflows/README.md`](./workflows/README.md) 所列阶段运行，每阶段只保留高密度产物进入下一阶段。
4. 统一使用 [`templates/README.md`](./templates/README.md) 中的模板生成 `CLAUDE.md`、`AGENTS.md`、`ANALYSIS.md`、`TODO.yaml`、Spec 和 handoff 文档。
5. 发生技术栈偏离、模型切换、来源冲突时，先写入 [`decisions/README.md`](./decisions/README.md) 中的 ADR，再继续执行。

## Exit Criteria
- 新同事能在不回看原始源文档的前提下，完成至少一轮 `Setup -> Research/Spec -> Code/Alignment` 的准备
- 任何核心规则都能追溯到一个明确源资产
- 多 agent 分工、handoff 契约和 reset 规则清晰且无冲突

## Failure Recovery
- 如果发现规则冲突，暂停扩写，回到 [`sources/README.md`](./sources/README.md) 与 ADR 检查来源优先级
- 如果阶段输入过大或输出发散，按 [`foundations/context-engineering.md`](./foundations/context-engineering.md) 收缩上下文并重置线程
- 如果交付物不能直接执行，优先回看对应 playbook 与模板，而不是回退到原始会议长文

## Related Templates
- [`templates/claude-md-template.md`](./templates/claude-md-template.md)
- [`templates/agents-md-template.md`](./templates/agents-md-template.md)
- [`templates/analysis-template.md`](./templates/analysis-template.md)
- [`templates/todo-yaml-template.md`](./templates/todo-yaml-template.md)
- [`templates/agent-handoff-template.md`](./templates/agent-handoff-template.md)
- [`templates/acceptance-checklist-template.md`](./templates/acceptance-checklist-template.md)

## 目录总览

| 目录 | 作用 |
|---|---|
| `sources/` | 源资产摘要、规则提炼、冲突记录、追溯矩阵 |
| `foundations/` | 长期稳定的原则层知识 |
| `platform/` | 技术栈白名单、框架决策、模型策略 |
| `orchestration/` | `CC Switch` 多 agent 编排与 handoff 契约 |
| `workflows/` | 7 阶段执行版流程 |
| `playbooks/` | 面向具体项目情境的执行路径 |
| `templates/` | 标准输入输出模板 |
| `decisions/` | 可变策略 ADR 和冲突决策 |

## 7 阶段总览

| 阶段 | 目标 | 核心产物 | 默认主模型 | 默认辅模型 |
|---|---|---|---|---|
| 0 Setup | 项目初始化与规则对齐 | `.meetings/`, `.ralphy/config.yaml`, `CLAUDE.md`, `AGENTS.md` | `GPT-5.4 Pro xhigh` | `Claude Opus 4.6` |
| 1 Research | 形成调研结论 | `ANALYSIS.md`, `TODO.yaml`, `.research/*.md` | `GPT-5.4 Pro xhigh` | `Claude Opus 4.6` |
| 2 Spec | 形成可实施规范 | `SPECS/*.md` | `GPT-5.4 Pro xhigh` | `Claude Opus 4.6` |
| 3 Code | 按 Spec 实施代码 | `.plans/*.md`, 代码与测试 | `GPT-5.4 Pro xhigh` | `Claude Opus 4.6` |
| 4 Alignment | 补齐 Spec 与代码缺口 | `ANALYSIS.md`, `TODO.yaml`, 补齐实现 | `GPT-5.4 Pro xhigh` | `Claude Opus 4.6` |
| 5 Refinement | 做全局质量收敛 | 简化、重构、模块化/结构重组计划 | `Claude Opus 4.6` | `GPT-5.4 Pro xhigh` |
| 6 Acceptance | 人工验收与交付确认 | 验收报告、发布决定 | 人工主导 | `Claude Opus 4.6` |

## Playbook 选择器

| 你当前的情况 | 直接打开 |
|---|---|
| 新项目，要从脚手架和约束开始 | [`playbooks/new-project-from-scaffold.md`](./playbooks/new-project-from-scaffold.md) |
| 老项目没有完整规范，要补 Spec 并顺带重构 | [`playbooks/existing-project-spec-backfill-and-refactor.md`](./playbooks/existing-project-spec-backfill-and-refactor.md) |
| 已有 Spec，但代码和 Spec 不一致 | [`playbooks/spec-code-alignment-gap-closure.md`](./playbooks/spec-code-alignment-gap-closure.md) |

## Source Precedence
1. 同一主题冲突时，优先更晚、更新、更可执行的来源。
2. `workflow.zip` 提供阶段骨架，会议整理文档提供原则与经验修正。
3. `skills.zip` 提供技能级执行约束，优先用于定义任务颗粒度和质量检查点。
4. 任何取舍都要落到 [`decisions/ADR-2026-03-21-source-precedence-and-conflict-resolution.md`](./decisions/ADR-2026-03-21-source-precedence-and-conflict-resolution.md)。