# 外挂总知识库初始内容

外挂总知识库最初必须先设定目录、元数据和种子内容，否则后续会变成散乱文档堆。第一版不追求内容多，重点是覆盖 Agent 高频决策面。

## 初始内容原则

- 每个条目必须能指导任务决策、实现、评审或验证。
- 每个条目必须带 `source_references`，没有来源的经验只进入 `draft`。
- 每个条目必须声明适用阶段和不适用边界。
- 初始内容以 `draft` 为主，除非已有多项目证据或人工审批。
- 不搬运完整文档，只抽取可执行判断。
- GitHub、官方文档和公开文章只能用于调研和提炼模式，不直接复制原文。

## 知识来源优先级

基础通用知识不是从 GitHub 直接复制出来的。它应该来自可授权、可追溯、可验证的来源，并由 Codex 或维护者改写为团队自己的短条目。

| 来源 | 应收集什么 | 使用方式 | 风险控制 |
| --- | --- | --- | --- |
| 团队真实项目经验 | trace、review finding、bug 修复、部署失败、测试缺口、事故复盘 | 作为最优先来源，初始为 `draft`，复用验证后升级 | 必须保留项目、任务、commit 或 trace 引用 |
| 官方文档和标准 | 框架推荐做法、语言规范、安全标准、测试工具规则 | 摘要关键判断并链接来源，不复制全文 | 标明版本、适用范围和不适用条件 |
| 优秀开源项目实践 | 目录结构、测试策略、CI、ADR、issue 模板、贡献流程 | 借鉴模式并重写为通用经验 | 不复制代码和文档原文，不照搬项目私有命令 |
| 公开文章和案例 | 工程复盘、架构讨论、经验总结 | 作为候选启发，不作为强约束 | 初始只能是 `draft`，需要后续项目验证 |
| 人工访谈和团队约定 | 业务规则、历史坑、团队偏好、内部流程 | 记录来源人、日期和适用项目 | 没有验证前不能升级为 `proven` |

## 首批内容范围

第一批只收 Agent 开发最容易影响成败的通用知识，不做百科全书。

| 分类 | 首批应包含 | 不应包含 |
| --- | --- | --- |
| `quality-management/requirements-quality` | 需求可测试性、验收标准、Requirement ID、追溯矩阵、防止 AI 扩 scope | 泛产品方法论长文 |
| `quality-management/verification-engineering` | `git diff --check` 边界、feature_impl 真实验证、affected tests、mock/test double 使用边界 | 只适用于单个测试框架的长教程 |
| `quality-management/review-gates` | Stage 1/2 分工、finding 格式、repair queue、复验规则 | 只看代码风格的 checklist |
| `software-engineering/task-decomposition` | task.json 拆分、owned paths、dependencies、单任务闭环 | 当前项目一次性路径 |
| `software-engineering/architecture-constraints` | 架构约束包字段、交付形态、公开入口、数据边界、异步边界、`not_applicable` 规则 | 某个项目的部署拓扑细节 |
| `software-engineering/integration-quality` | contract first、真实依赖、mock 切真实接口、联调证据 | 未验证的集成偏好 |
| `agent-engineering/workflow-control` | driver-first、truth source、BLOCKED 协议、不伪造状态 | 聊天偏好 |
| `agent-engineering/prompt-and-rule-governance` | AGENTS/prompt/template 写入边界、何时升级规则、敏感信息禁令 | 未确认团队习惯 |
| `agent-engineering/multi-agent-coordination` | 并行任务、写路径隔离、handoff、review 复验 | 多 Agent 概念介绍 |
| `agent-engineering/knowledge-governance` | draft/verified/proven、冲突、衰减、归档、团队同步 | 没有 evidence 的“最佳实践” |

## 从外部来源提炼条目的流程

```text
1. 明确要解决的 Agent 决策问题。
2. 搜索官方文档、开源项目实践或团队历史记录。
3. 只提炼可执行判断，不搬运完整内容。
4. 写成 100-300 字短条目。
5. 加 source_references、适用阶段、不适用条件和 maturity=draft。
6. 后续任务真正引用并验证后，再考虑升级 verified/proven。
```

示例条目：

```markdown
---
id: GUIDELINE-TESTING-001
type: guideline
domain: quality-management
subdomain: verification-engineering
maturity: draft
tags: [testing, verification]
source_references:
  - project: codex-herness
    ref: docs/harness/regression-rules.md
  - url: https://playwright.dev/docs/test-assertions
applicable_phases: [implement, review, verify]
last_referenced:
validated_projects: []
contradictions: []
contributors:
  - codex
---

# feature_impl 不能只用格式检查作为完成验证

## Guidance

实现任务必须至少运行一个能证明用户故事、接口行为或交付路径的验证命令。`git diff --check` 只能证明文本格式，不证明功能完成。

## Not Applicable When

任务明确是纯文档、索引或模板格式改动。

## Evidence

初始来源为 Harness 任务执行规则和测试工具文档，待后续项目 trace 验证。
```

## 必建目录

```text
team-wiki/
  knowledge-catalog.md
  .knowledge-config.yaml
  log.md
  quality-management/
    catalog.md
    requirements-quality/
    verification-engineering/
    review-gates/
    risk-management/
  software-engineering/
    catalog.md
    task-decomposition/
    architecture-constraints/
    integration-quality/
    change-management/
  agent-engineering/
    catalog.md
    workflow-control/
    prompt-and-rule-governance/
    multi-agent-coordination/
    knowledge-governance/
  project-profiles/
    catalog.md
  contributions/
    pending/
    conflicts/
  archive/
```

## 初始全景目录

`knowledge-catalog.md` 应先写清楚：

- 本知识库服务哪些项目和团队。
- 查询顺序：全景目录 -> 分类 catalog -> 条目。
- 成熟度规则：`draft` / `verified` / `proven`。
- 冲突规则：项目事实优先，团队知识冲突进入 `contributions/conflicts/`。
- 写入规则：自动化只写 pending，不直接改主干知识。

## 初始配置

`.knowledge-config.yaml` 最小内容：

```yaml
schema_version: 1
team:
  name: codex-harness-team
  default_role: reader
roles:
  maintainers: []
  contributors: []
sync:
  accept_domains: [quality-management, software-engineering, agent-engineering]
  require_maintainer_for_proven: true
  allow_auto_pending: true
conflicts:
  on_content_conflict: stage_to_conflicts
  on_maturity_conflict: keep_lower_and_mark_contradiction
decay:
  proven_months_without_reference: 12
  verified_months_without_reference: 6
```

## 第一批种子内容

### Requirements Quality

| ID | 类型 | 标题 | 初始成熟度 | 为什么先建 |
| --- | --- | --- | --- | --- |
| GUIDELINE-REQ-001 | guideline | P0/P1 需求必须有可测试验收标准 | draft | 防止 AI 凭感觉实现 |
| GUIDELINE-REQ-002 | guideline | Requirement ID 必须能追溯到 UI/API/数据/测试 | draft | 支撑 Stage 1 Review |
| PITFALL-REQ-001 | pitfall | 未收敛需求直接编码会造成 scope 漂移 | draft | AI 编程高频失败 |

### Verification Engineering

| ID | 类型 | 标题 | 初始成熟度 | 为什么先建 |
| --- | --- | --- | --- | --- |
| GUIDELINE-VERIFY-001 | guideline | feature_impl 不能只用格式检查作为完成验证 | draft | 防止假完成 |
| GUIDELINE-VERIFY-002 | guideline | 完成声明必须有 fresh evidence | draft | 防止编造完成 |
| PITFALL-VERIFY-001 | pitfall | Release 阶段第一次补测试范围会掩盖需求缺口 | draft | Harness 阶段约束 |
| PROCESS-VERIFY-001 | process | affected tests 选择流程 | draft | 支撑验证工程 |

### Review Gates

| ID | 类型 | 标题 | 初始成熟度 | 为什么先建 |
| --- | --- | --- | --- | --- |
| PROCESS-REVIEW-001 | process | Stage 1 审产品、设计、计划和架构约束 | draft | 防止评审职责混杂 |
| PROCESS-REVIEW-002 | process | Stage 2 审代码质量、测试、安全和回归风险 | draft | 防止只看需求不看实现 |
| GUIDELINE-REVIEW-001 | guideline | Finding 必须包含 owner、evidence 和 repair queue | draft | 让修复可执行 |

### Task Decomposition

| ID | 类型 | 标题 | 初始成熟度 | 为什么先建 |
| --- | --- | --- | --- | --- |
| GUIDELINE-TASK-001 | guideline | 单个 task 必须有 owned paths 和独立验证闭环 | draft | 防止大任务失控 |
| GUIDELINE-TASK-002 | guideline | release 任务只刷新证据，不首次补范围 | draft | 保持阶段职责 |
| PITFALL-TASK-001 | pitfall | 多 Agent 同时写同一路径会造成不可控冲突 | draft | 并行协作常见坑 |

### Architecture Constraints

| ID | 类型 | 标题 | 初始成熟度 | 为什么先建 |
| --- | --- | --- | --- | --- |
| GUIDELINE-ARCH-001 | guideline | 每个实现任务应声明交付形态、公开入口和数据边界 | draft | 支撑通用架构约束包 |
| GUIDELINE-ARCH-002 | guideline | 不适用的边界必须写 `not_applicable` 而不是留空 | draft | 防止 Agent 猜测 |
| PITFALL-ARCH-001 | pitfall | 测试替身冒充声明交付路径会导致验收失真 | draft | 来自近期架构约束门禁需求 |

### Agent Workflow Control

| ID | 类型 | 标题 | 初始成熟度 | 为什么先建 |
| --- | --- | --- | --- | --- |
| DECISION-AGENT-001 | decision | Driver-first 优先于聊天内手工维护任务状态 | draft | 当前 Harness 核心架构决策 |
| GUIDELINE-AGENT-001 | guideline | 实现任务必须带 truth source、owned paths 和验证命令 | draft | 防止任务不可验证 |
| PROCESS-AGENT-001 | process | BLOCKED 输出和人工介入协议 | draft | 防止伪继续 |

### Prompt And Rule Governance

| ID | 类型 | 标题 | 初始成熟度 | 为什么先建 |
| --- | --- | --- | --- | --- |
| GUIDELINE-RULE-001 | guideline | AGENTS 只放入口硬约束，细节放深文档 | draft | 防止根规则膨胀 |
| GUIDELINE-RULE-002 | guideline | 单次经验先进入知识库，不直接升级 prompt/template | draft | 控制规则污染 |

### Knowledge Governance

| ID | 类型 | 标题 | 初始成熟度 | 为什么先建 |
| --- | --- | --- | --- | --- |
| PROCESS-KNOWLEDGE-001 | process | 知识条目从项目归档提升到团队库的流程 | draft | 防止直接把项目经验升全局规则 |
| GUIDELINE-KNOWLEDGE-001 | guideline | 项目事实优先于外挂知识 | draft | 防止团队库误覆盖当前项目 truth source |
| GUIDELINE-KNOWLEDGE-002 | guideline | draft 知识不能作为阻塞性 Review 依据 | draft | 控制误杀 |
| PROCESS-KNOWLEDGE-002 | process | 团队知识冲突进入 pending/conflicts 并人工裁决 | draft | 解决多项目结论矛盾 |

### Project Profiles

| ID | 类型 | 标题 | 初始成熟度 | 为什么先建 |
| --- | --- | --- | --- | --- |
| MODEL-PROJECT-001 | model | 项目画像最小字段 | draft | 支持按项目过滤知识 |

项目画像最小字段：

```yaml
project_slug:
domains: []
tech_stack: []
delivery_shape:
knowledge_sources:
  project: docs/knowledge
  team:
validated_rules: []
known_conflicts: []
```

## 条目模板

```markdown
---
id: <TYPE-AREA-NNN>
type: guideline
domain: quality-management
subdomain: verification-engineering
maturity: draft
tags: []
applicable_phases: []
source_references:
  - project:
    ref:
last_referenced:
validated_projects: []
contradictions: []
contributors:
  - codex
---

# <title>

## Context

## Guidance

## Not Applicable When

## Evidence
```

## 不要首批加入的内容

- 大段框架官方文档。用链接和摘要，不复制全文。
- 未验证的个人偏好。
- 只适用于单个项目的路径、命令和部署细节。
- 没有替代方案的禁令。
- 没有 source reference 的“最佳实践”。
- 会泄露 token、cookie、私钥、客户数据或内部密钥的内容。

## 初始验收标准

第一版外挂总知识库达到以下状态即可开始试用：

- `knowledge-catalog.md` 存在并说明查询顺序。
- 每个一级目录都有 `catalog.md`。
- 至少 10 条种子知识，全部有 frontmatter。
- 所有种子条目默认为 `draft`，除非有明确 evidence。
- `.knowledge-config.yaml` 存在。
- `log.md` 存在，并记录初始化动作。
- 项目侧 `.knowledge-sources.yml` 可以指向该仓库。
