项目经验库要能被反复检索和复用，单条经验需要一张结构固定的经验卡：字段记录事实与结论，标签负责分类与召回。本文提供一张可直接复制的空白表格，并逐项说明填写口径、必填规则、标签受控取值与维护方法，适合项目复盘后由当事人或知识管理员录入。经验卡最终要落到可协作的文档载体上，ONES Wiki 的页面模板库与项目关联能力可作为承载方式之一。
要点总览（TL;DR）
- 单条项目经验建议用一张固定经验卡承载，按标识与来源、问题与情境、做法与结论、复用与维护四个分区组织字段。
- 经验编号、项目名称、项目类型、所处阶段、问题类别、触发条件、处理动作、结论、适用边界、维护人、更新时间建议设为必填，保证可追溯、可检索、可安全复用。
- 标签使用受控词表，按项目类型、阶段、问题类别、技术域、结论类型五组取值；主标签1–2个承担场景召回，次标签不超过4个用于细化筛选。
- 结论与适用边界成对填写，复用次数注明统计周期与登记来源，避免数字口径不一。
- 模板设版本号与变更记录，字段增减和标签归并走申请与复核，按季度对照检索记录检查召回效果。
可复制空白经验卡模板
下表可直接复制到文档或表格工具中使用。字段按四个分区排列，标签单独成栏，避免把分类信息混进正文描述。填写时保留字段名，删除“填写区”中的提示文字。
| 分区 | 字段名 | 填写区 |
|---|---|---|
| 标识与来源 | 经验编号 | （如 EXP-2024-015） |
| 项目名称 | （项目全称，与项目管理系统一致） | |
| 项目类型 | （取自标签词表：项目类型组） | |
| 所处阶段 | （取自标签词表：阶段组） | |
| 问题与情境 | 问题类别 | （取自标签词表：问题类别组） |
| 触发条件 | （什么情况下会遇到，含前置条件与信号） | |
| 影响范围 | （受影响的对象、环节与程度） | |
| 情境描述 | （背景与过程，200字以内） | |
| 做法与结论 | 处理动作 | （按步骤写，每步一个动作） |
| 结论 | （有效做法、无效做法或待验证判断） | |
| 适用边界 | （在什么条件下成立，什么条件下不适用） | |
| 反例或失败教训 | （尝试过但未奏效的做法及原因） | |
| 复用与维护 | 复用场景 | （哪些项目、阶段或角色可直接参考） |
| 复用次数 | （登记次数＋统计周期，如 3 次/近半年） | |
| 维护人 | （姓名或角色） | |
| 更新时间 | （YYYY-MM-DD） | |
| 标签区 | 主标签／次标签 | （按标签词表填写，主标签1–2个，次标签不超过4个） |
表格之外建议保留两个附属位置：一是“关联工作项”，填写触发该经验的需求、缺陷或任务编号；二是“附件”，存放截图、日志或原始文档。这两项不进入字段主体，但决定了经验能否回溯到原始现场。
字段说明：每个字段填什么、怎么填
同一字段在不同人手里写出不同口径，是经验库失效的常见原因。下表给出每个字段的含义、填写口径与示例值，录入时按口径写，不按个人习惯写。
| 字段名 | 含义 | 填写口径 | 示例值 |
|---|---|---|---|
| 经验编号 | 经验条目的唯一标识 | 采用“前缀-年份-流水号”，由知识管理员统一分配，不重复使用 | EXP-2024-015 |
| 项目名称 | 经验来源项目 | 写项目全称，与项目管理系统中的名称一致，便于反查 | 客户门户重构项目 |
| 项目类型 | 项目所属类别 | 从标签词表“项目类型”组中选一个，不自由填写 | 交付实施类 |
| 所处阶段 | 问题发生的项目阶段 | 从“阶段”组选一个；跨阶段问题选主要发生阶段，并在情境描述中补充 | 联调测试 |
| 问题类别 | 经验针对的问题类型 | 从“问题类别”组选一个主类，必要时加次类 | 接口联调 |
| 触发条件 | 问题出现的条件与信号 | 写可观察的前置条件，避免“沟通不畅”这类无法判断的描述 | 第三方接口在压测并发超过200时返回超时 |
| 影响范围 | 问题波及的对象与程度 | 写清受影响模块、角色与时间成本 | 影响订单模块联调，延期2天 |
| 情境描述 | 背景与经过 | 200字以内，按时间顺序写关键节点，不写评价性内容 | 联调第二周发现…… |
| 处理动作 | 实际采取的做法 | 分步骤写，每步一个动作，标注责任角色 | 1. 抓包定位超时点；2. 与对方约定重试策略…… |
| 结论 | 经验的核心判断 | 明确写“有效”“无效”或“待验证”，待验证需注明验证条件 | 有效：提前约定超时与重试参数可减少联调返工 |
| 适用边界 | 结论成立的条件 | 写清技术栈、团队规模、接口类型等限制，边界越具体复用越安全 | 适用于外部接口由第三方维护、且无法修改服务端的场景 |
| 反例或失败教训 | 未奏效的做法 | 写做法与失败原因，避免只写“不可行” | 直接调大本地超时时间，掩盖了对方限流问题 |
| 复用场景 | 可参考的项目与角色 | 写具体场景而非“所有项目” | 新项目接入第三方支付接口前的联调准备 |
| 复用次数 | 被引用或复用的登记次数 | 注明统计周期与登记人，口径统一为“被其他项目引用并登记” | 3 次/近半年 |
| 维护人 | 对该条经验负责的人 | 写姓名或角色，人员变动时移交并更新 | 后端负责人 张某 |
| 更新时间 | 最近一次修订日期 | 每次修改内容后更新，仅改标签也需更新 | 2024-06-18 |
填写时有两个一致性要求：项目类型、阶段、问题类别三个字段的取值必须与标签区完全一致，不能字段写“联调测试”、标签写“测试阶段”；结论与适用边界要成对出现，只写结论不写边界，复用者无法判断能否照搬。
必填与选填：哪些字段不能空
经验卡的价值取决于能否被找到、被判断、被追责。以下三档划分以“缺了就无法检索或无法安全复用”为标准，团队可在此基础上增加字段，不建议减少必填项。
| 档位 | 字段 | 理由或触发条件 |
|---|---|---|
| 必填 | 经验编号、项目名称、项目类型、所处阶段、问题类别、触发条件、处理动作、结论、适用边界、维护人、更新时间 | 编号与来源保证可追溯；问题类别与阶段保证可检索；触发条件、处理动作、结论、适用边界共同构成可复用内容；维护人与更新时间保证条目有人负责 |
| 条件必填 | 反例或失败教训 | 结论为“无效”或“待验证”时必须填写；结论为“有效”且存在被否决方案时建议填写 |
| 条件必填 | 复用场景 | 经验被标记为“可推广”时必须填写；仅作项目内部记录时可暂缺 |
| 选填 | 影响范围、情境描述、复用次数 | 影响范围在问题波及多个模块时补充；复用次数在首次复用登记后回填 |
字段暂时无法填写时，用统一标注代替留空：写“待补充”并注明补充责任人与期限，例如“待补充（张某，两周内）”。避免用“无”“暂无”混用，否则后续统计无法区分“确实没有”和“还没填”。经验编号不允许空缺或后补，它是关联工作项与附件的锚点。
标签体系：受控词表与打标规则
标签的作用是把经验按场景召回，因此取值必须受控。自由填写的标签很快会出现“联调”“接口联调”“第三方联调”并存的情况，检索时互相漏掉。建议按以下五组建立词表，每组限定取值，新增走申请。
| 标签组 | 受控取值示例 | 打标规则 |
|---|---|---|
| 项目类型 | 交付实施类、产品研发类、内部工具类、运维保障类 | 单选，与字段“项目类型”一致 |
| 阶段 | 需求分析、方案设计、开发实现、联调测试、上线发布、运维运营 | 单选，跨阶段问题选主要阶段 |
| 问题类别 | 需求变更、接口联调、进度协同、质量缺陷、环境配置、人员交接 | 单选主类，可加一个次类 |
| 技术域 | 前端、后端、数据、基础设施、第三方集成 | 可多选，最多两个 |
| 结论类型 | 有效做法、失败教训、待验证判断 | 单选，与字段“结论”的表述对应 |
标签数量上，单条经验建议主标签1–2个、次标签不超过4个。主标签从项目类型、阶段、问题类别中选取，承担场景召回；次标签从技术域和结论类型中选取，用于细化筛选。主次之分要在标签区明确标注，避免全部平铺导致召回排序失准。
新增标签需提交申请，写明拟用名称、所属组、与现有取值的区别，由知识管理员按月归并。含义相近的标签合并到保留项，历史条目批量替换并记录变更。标签与字段的对应关系保持单向：字段是事实描述，标签是分类索引，同一信息不在两处用不同措辞重复表达。
填写示例：一条完整经验
以下示例展示字段与标签如何配合，可直接对照空白模板理解填写深度。
| 字段 | 填写内容 |
|---|---|
| 经验编号 | EXP-2024-015 |
| 项目名称 | 客户门户重构项目 |
| 项目类型 | 交付实施类 |
| 所处阶段 | 联调测试 |
| 问题类别 | 接口联调 |
| 触发条件 | 第三方支付接口由对方维护，压测并发超过200时返回超时，且对方未提供限流说明 |
| 影响范围 | 订单模块联调阻塞2天，测试团队等待环境 |
| 情境描述 | 联调第二周压测出现批量超时，初期怀疑本地网络，排查一天后确认对方存在未公开的限流策略。 |
| 处理动作 | 1. 抓包与日志比对定位超时点；2. 与对方技术对接人确认限流阈值；3. 约定重试与退避参数并写入接口文档；4. 在测试用例中补充并发边界场景。 |
| 结论 | 有效：接入外部接口前书面确认限流与超时参数，可显著减少联调返工。 |
| 适用边界 | 适用于接口由第三方维护、服务端不可修改的场景；内部自研接口不适用此做法。 |
| 反例或失败教训 | 先调大本地超时时间，掩盖了对方限流问题，导致上线后仍出现超时。 |
| 复用场景 | 新项目接入第三方支付或物流接口前的联调准备 |
| 复用次数 | 3 次/近半年（由复用项目登记） |
| 维护人 | 后端负责人 张某 |
| 更新时间 | 2024-06-18 |
| 主标签 | 交付实施类、联调测试、接口联调 |
| 次标签 | 第三方集成、有效做法 |
这条经验的复用价值来自两处：适用边界写明了“第三方维护、服务端不可修改”，复用者能快速判断自己的场景是否匹配；复用次数带统计周期和登记来源，避免数字被随意累加。检索时，按“联调测试＋接口联调”可召回同类经验，按“第三方集成”可扩展到其他外部依赖场景。
当经验卡数量增长后，检索与召回依赖文档载体本身的组织方式。ONES Wiki 支持页面组关联项目、需求与文档互相对应，经验卡可以放在对应项目的页面组下，与触发它的需求、任务保持关联；页面模板库可用于统一经验卡格式，全局搜索可覆盖正文与附件内容。这样，经验从项目现场产生，录入后仍能回到项目语境中被找到。
模板调整与长期维护
模板在使用中会暴露两类问题：字段填了但没人用，标签建了但召不回。维护的目标是让字段和标签随实际检索行为调整，而不是随个人偏好增减。
字段与标签的调整触发条件建议明确为三种：连续一个季度某选填字段填写率低于三成，考虑删除或并入其他字段；同一标签组每月新增申请超过三个，说明词表粒度需要重新划分；检索日志中某类经验被反复搜索却召回不足，优先补充对应标签或调整主标签规则。
| 变更项 | 记录内容 | 示例 |
|---|---|---|
| 版本号 | 模板整体版本，按次递增 | v1.2 |
| 变更日期 | 生效日期 | 2024-07-01 |
| 变更类型 | 字段新增／字段删除／标签归并／口径修订 | 标签归并 |
| 变更说明 | 改了什么、为什么改 | “接口联调”与“第三方联调”合并为“接口联调” |
| 影响范围 | 涉及的历史条目数量与处理方式 | 涉及12条，已批量替换 |
| 复核人 | 批准变更的人 | 知识管理员 李某 |
维护责任建议由知识管理员承担日常复核，字段口径类变更由项目负责人共同确认。复核节奏可按季度进行：抽查新录入经验卡的必填完整率、标签取值合规率，并对照检索记录检查高频问题是否都有对应经验。若某类问题长期搜不到经验，说明录入端存在缺口，应回到项目复盘环节补录，而非继续扩充标签。
模板版本变更后，历史条目不必全部重填，但需在条目中保留原版本号，便于区分口径差异。经验卡与项目工作保持关联时，ONES Wiki 可将文档与项目、任务结合使用，使经验条目在项目结束后仍可回溯到原始工作项；具体字段化与统计能力以实际使用版本为准，团队可在文档内自行维护复用登记。
常见问题
经验卡里的“项目类型”“阶段”“问题类别”字段和标签区重复，应该填几遍？
字段和标签各填一次，但取值必须完全一致。字段承担事实描述，标签承担分类索引，同一信息在两处用同一措辞表达。实际操作中可先确定标签取值，再把相同取值回填到字段，避免出现字段写“联调测试”、标签写“测试阶段”的错位。若团队使用带属性配置的文档或表格工具，也可以让字段直接引用标签词表，减少手工重复。
经验刚产生时复用次数还是0，这个字段可以先空着吗？
可以。复用次数属于选填字段，首次录入时留空或用统一标注“待回填”即可，等被其他项目引用并登记后再补。关键是统一计数口径：只统计“被其他项目引用并完成登记”的次数，并注明统计周期，例如“3 次/近半年”。若把口头提及、作者自己再次查阅都算进去，数字会失去参考价值。
结论写“待验证”的经验，是否适合放进项目经验库？
适合，但要写清验证条件与验证责任人。待验证判断往往对应尚未定论的新做法，对后续项目有提醒价值。填写时在结论字段注明“待验证”及需要满足的验证条件，在反例或失败教训字段说明已观察到的问题，并把结论类型标签选为“待验证判断”。这样检索者能区分可直接照搬的有效做法与仍需观察的判断，避免误用。
标签词表由谁维护，一线项目成员能否自行新增标签？
建议由知识管理员统一维护词表，一线成员通过申请新增。申请时写明拟用名称、所属标签组、与现有取值的区别，管理员按月归并含义相近的标签，历史条目批量替换并记录变更。若放开自由新增，很快会出现“联调”“接口联调”“第三方联调”并存，检索时互相漏掉。成员确有新场景需求时，走申请比自行填写更利于长期召回。
经验卡录入后放在哪里，才能让后续项目真正找到它？
建议把经验卡放在与来源项目对应的文档空间，并与触发它的需求、任务或缺陷保持关联，让经验回到项目语境中。ONES Wiki 支持页面组关联项目、需求与文档互相对应，页面模板库可用于统一经验卡格式，全局搜索可覆盖正文与附件内容（具体可用范围以实际版本为准）。这样检索者既能按标签筛选，也能从项目、工作项反查到经验条目。
