project-docs-knowledge-log-zh

name	project-docs-knowledge-log-zh
description	项目 docs 知识点沉淀技能：在完成有复用价值的项目问答、代码解释、工作流讲解、设计决策或排错复盘后，把本轮最关键的 1 个知识点写入当前项目 docs/knowledge/ 的单篇 Markdown 文档。Use when: 每次问答结尾、项目知识沉淀、docs 知识库、一个知识点一篇文档、问答复盘、技术概念小白解释、工作流经验记录、代码链路解释记录。不适用于：闲聊、简单确认、纯文件操作、没有可复用知识点的任务。

项目 docs 知识点沉淀

Project structure gate / 文件树结构门禁

只要本工作流将初始化或重组项目，或新建、移动应用、服务、包、模块、页面、API、研究步骤、实验、流水线、测试、文档或多文件产物树，必须先使用 project-structure-architect。

1. 开始前：读取适用的 AGENTS.md、PROJECT_STRUCTURE.md、.project-structure.yaml 和现有文件树，锁定项目类型、蓝图及唯一合理路径。
2. 运行中：每次新增或移动文件前先判断职责、所有者、复用范围和对应测试；禁止同义目录、根目录堆放、跨层混放及无关重组。
3. 阶段收口：纵向切片或阶段完成后检查结构漂移；新项目或重大重组更新结构文档，最终运行结构审计。出现 BLOCK 时停止结构性写入并先修正或询问用户。

纯内容编辑且目标路径已由用户或现有规范唯一确定时，可不重复调用。

目标

把一次问答里最值得复用的知识点，沉淀到当前项目自己的 docs/knowledge/ 中。这个技能只负责项目内长期文档，不替代 knowledge-digest-zh 的最终回复学习摘要。

触发判断

触发本技能前先做三步判断：

1. 当前任务是否有项目上下文：当前目录或用户指定目录包含 .git、README、docs、src、package.json、pyproject.toml、Cargo.toml、go.mod、pom.xml 等项目特征之一。
2. 本轮是否产生可复用知识：代码链路解释、排错方法、设计取舍、工程流程、工具用法、概念小白解释、项目约定都算。
3. 是否值得写成长期文档：未来在同项目里再次遇到时，读这篇文档能减少重复解释。

任一判断不满足时跳过写入。不要因为闲聊、简单确认、纯文件移动、skill 自身维护、没有新知识点的答复而创建文档，除非用户明确要求记录。

写入位置

• 默认目录：docs/knowledge/
• 如果项目已有 docs/，在其下创建或使用 knowledge/
• 如果项目没有 docs/ 但满足项目特征，创建 docs/knowledge/
• 如果用户指定了别的文档目录，以用户指定为准

不要把本技能的项目知识文档写到 skill-outputs/。skill-outputs/ 仍留给一次性总结、报告或其他技能产物。

选择知识点

每次只写 1 个知识点。若本轮出现多个候选，按下面顺序选择：

1. 最能帮助用户下次独立判断或操作的知识点
2. 最贴近当前项目长期维护的知识点
3. 最容易被误解、且值得用小白例子讲清楚的知识点
4. 最能解释本次关键决策或错误根因的知识点

不要把整轮对话改写成流水账，也不要把多个不相关知识点塞进一篇文档。

文件命名

使用稳定、可搜索、短小的 slug：

docs/knowledge/<topic-slug>.md

命名规则：

• 优先使用英文技术词，例如 vertical-slice-incremental-build.md
• 中文概念可用简短拼音或英文释义，例如 project-docs-knowledge-log.md
• 全部小写，用 - 分隔
• 不使用日期前缀，除非用户明确要求按日期归档
• 同一知识点后续继续更新原文档，不新建重复文件

写入前先快速检查 docs/knowledge/ 中是否已有同主题文档。判断同主题时同时看文件名、一级标题和核心概念，不只看完全同名。

文档模板

新建文档时使用以下固定结构：

# 知识点标题

## 一句话理解

[用一句话说清楚这个知识点是什么。]

## 为什么本项目会遇到

[说明它和当前项目、当前问题、当前工作流的关系。]

## 小白例子

[用生活化或项目内的简单例子解释，避免抽象术语堆叠。]

## 实战做法

[列出下次遇到类似问题时可以直接照做的步骤。]

## 常见坑

[列出 2-4 个最容易误用或遗漏的点。]

## 下次怎么判断

[给出判断标准：什么时候该用、什么时候不该用、看到什么信号要触发。]

## 关联上下文

- [YYYY-MM-DD] [一句话说明这篇文档来自哪类问答或项目场景。]

更新已有文档时保持以上结构，不要改成聊天记录。把新信息合并进最相关的小节，并在 关联上下文 中追加一条日期记录。

收口回复

如果写入了文档，在最终回复中用一句话说明路径：

已沉淀知识点文档：docs/knowledge/<topic-slug>.md

如果按触发判断跳过，不需要强行解释；只有用户明确要求记录但本轮不适合记录时，才简短说明跳过原因。