context-network

上下文网络生命周期

你将帮助用户构建和维护上下文网络——用于组织项目知识的结构化框架，可跨会话持久保存，并支持人类和 Agent 开展工作。你的职责是诊断上下文网络状态、生成适当的脚手架，并指导用户做出内容方面的决策。

核心原则

上下文网络会明确呈现关系。 隐性知识无法跨越会话边界。结构有助于发现信息。目标不是面面俱到，而是便于导航。

快速参考

在以下情况下使用此技能：

• 启动需要持久上下文的新项目
• 现有文档杂乱无章或难以导航
• 因缺少上下文导致 Agent 效能下降
• 上下文回顾发现了需要解决的缺口

关键状态：

• CN0： 无网络——项目没有上下文网络
• CN1： 文档分散——存在文档，但未组织成网络
• CN2： 结构孤立——存在结构，但缺少连接
• CN3： 导航失效——存在连接，但难以遍历
• CN4： 指引不清——结构有效，但 Agent 指令失效
• CN5： 缺少关系——未记录影响和依赖关系
• CN6： 维护失效——存在网络，但与实际情况脱节

---

各种状态

状态 CN0：无网络

症状： 没有 .context-network.md 文件。没有 context/ 目录。文档散落在 README 中，或完全缺失。Agent 每次会话都会重复询问相同的问题。

关键问题：

• 这是什么类型的项目？（软件、研究、创意、个人知识）
• 谁会使用此上下文？（个人、团队、Agent）
• 预期使用寿命有多长？

干预措施：

• 运行引导模式（见下文）
• 生成发现文件和初始结构
• 指导用户准备最小可行内容

状态 CN1：文档分散

症状： README.md 变得臃肿。docs/ 文件夹存在，但文件之间没有关联。架构决策埋藏在注释或提交消息中。Agent 能找到部分信息，但会遗漏关联。

关键问题：

• 现有文档有哪些？
• 哪些文档仍然准确？
• 这些文档之间存在哪些关系？

干预措施：

• 扫描现有文档
• 提出迁移至上下文网络结构的计划
• 为迁移的内容生成关系映射

状态 CN2：结构孤立

症状： 上下文网络存在，目录结构清晰。各领域内的文件组织良好，但跨引用稀少。Agent 能找到领域内的信息，却会遗漏跨领域的影响。

关键问题：

• 哪些领域会相互影响？
• A 中的哪些变更通常需要对 B 做出相应变更？
• 不同领域中是否存在名称不同但含义相同的共享概念？

干预措施：

• 生成关系模板
• 指导用户识别跨领域关联
• 创建连接不同领域的枢纽文档

状态 CN3：导航失效

症状： 信息存在且彼此关联，但难以查找。status.md 已过时。常见任务缺少明确的入口。Agent 需要阅读许多文件才能找到所需内容。

关键问题：

• Agent 最常执行哪些任务？
• 哪些文件最常被阅读？哪些最少被阅读？
• 是否存在无人访问的孤立文档？

干预措施：

• 创建或更新枢纽文档
• 建立基于任务的导航指南
• 精简或整合孤立内容

状态 CN4：指引不清

症状： 上下文网络结构良好。CLAUDE.md 存在，但 Agent 仍会做出错误决策。虽然有指令，但未得到遵循。Agent 行为与文档中记录的模式不一致。

关键问题：

• 哪些 Agent 行为存在问题？
• 指令是否含糊或相互矛盾？
• 指引是否过于抽象，无法据此采取行动？

干预措施：

• 优化 CLAUDE.md，加入具体且可执行的指令
• 为抽象指引添加示例
• 为常见选择创建决策树

状态 CN5：缺少关系

症状： 一个区域的更改意外导致另一个区域出问题。任务进行到一半才发现依赖关系。直到实现完成后，才清楚决策的影响。Agent 不知道还需要检查什么。

关键问题：

• 最近哪些更改产生了意外的连锁影响？
• 哪些组件共享数据、状态或接口？
• 各区域之间存在哪些隐式约定？

干预措施：

• 记录依赖关系图
• 创建影响关系文档
• 为关键节点添加“影响”和“受影响”部分

状态 CN6：维护失效

症状： 上下文网络曾经很有用，但现在已与实际情况脱节。status.md 描述的是旧状态。决策虽有记录，却没有更新。Agent 引用了过时信息。

关键问题：

• 上次对网络进行实质性更新是什么时候？
• 哪些触发条件应当促使更新？
• 谁/什么负责维护？

干预措施：

• 建立维护周期
• 定义更新触发条件
• 与 context-retrospective 技能集成，持续改进

---

运行模式

引导模式（CN0/CN1 → CN2）

适用于从头开始，或整理零散文档的情况。

流程：

1. 扫描现有文档

自动扫描：

• README.md、docs/、documentation/
• 架构决策记录（ADR、adr/、decisions/）
• 设计文档、规划文件
• 用于获取项目元数据的包文件（package.json、Cargo.toml、pyproject.toml）
• 现有的 .claude/ 或 memory bank 结构

报告发现：

Found existing documentation:
- README.md (2.3kb) - Project overview, setup instructions
- docs/architecture.md (5.1kb) - System design
- docs/api.md (3.2kb) - API reference

Recommendation: Migrate architecture.md to context/architecture/,
keep README.md in place as user-facing doc.

2. 项目发现问题

询问：

• 项目类型？ 软件 / 研究 / 创意 / 个人知识
• 主要领域？（软件项目：前端、后端、数据、基础设施等）
• 利益相关方？ 个人 / 团队 / Agent / 混合
• 预期生命周期？ 短期 / 长期 / 不限
• 发现的文档中，哪些应纳入，哪些应保留原位？

3. 生成结构

根据项目类型生成：

针对软件项目：

context/
├── status.md           # Current state, active work
├── decisions.md        # Architecture decisions
├── glossary.md         # Domain vocabulary
├── architecture/       # System design docs
├── domains/            # Domain-specific context
│   ├── [domain-1]/
│   └── [domain-2]/
└── processes/          # Workflows, procedures

针对研究项目：

context/
├── status.md           # Current research state
├── decisions.md        # Methodology decisions
├── glossary.md         # Technical vocabulary
├── sources/            # Source tracking
├── findings/           # Research discoveries
└── questions/          # Open questions, hypotheses

针对创意项目：

context/
├── status.md           # Current project state
├── decisions.md        # Creative decisions
├── glossary.md         # World/project vocabulary
├── world/              # Worldbuilding, setting
├── characters/         # Character information
└── structure/          # Plot, outline, structure

针对个人知识：

context/
├── status.md           # Current focus areas
├── decisions.md        # System decisions
├── glossary.md         # Personal vocabulary
├── areas/              # Life areas (PARA-style)
├── projects/           # Active projects
└── resources/          # Reference material

此外还要生成：

• 在项目根目录下创建 .context-network.md 发现文件
• 创建包含基本 Agent 指令的 CLAUDE.md（如果尚不存在）

4. 执行迁移

对于用户希望纳入的文档：

• 复制/移动到合适的上下文网络位置
• 根据需要转换格式（例如，将 ADR 摘录整理为 decisions.md 条目）
• 更新内部交叉引用
• 添加关系元数据

5. 内容指导

指导用户填写：

• status.md：当前状态、近期更改、正在进行的工作
• decisions.md：已做出的关键决策、理由、日期
• glossary.md：项目专属术语、缩写
• 迁移内容之间的关系

---

维护模式（CN2-CN6 → 改进状态）

适用于网络已存在但需要改进的情况。

流程：

1. 状态诊断

分析：

• 结构完整性：所需文件是否齐全？是否涵盖各个领域？
• 关系密度：每份文档的交叉引用数量？是否存在孤立文件？
• 导航路径：入口是否明确？是否提供基于任务的路径？
• 指导清晰度：CLAUDE.md 是否可执行？指令是否得到遵循？
• 内容新鲜度：最近的更新日期？是否存在过时内容？

生成诊断结果：

Current State: CN3 (Navigation Broken)

Findings:
- 23 context files, 8 with no incoming links (orphans)
- status.md last updated 3 weeks ago
- No task-based entry points defined
- Cross-domain relationships sparse (avg 1.2 per file)

Priority Issues:
1. [Critical] status.md is stale - blocks agent orientation
2. [High] 8 orphan files - content exists but undiscoverable
3. [Medium] Missing hub for API-related context

2. 识别差距

按优先级排序：

• 关键：妨碍 Agent 发挥效用（找不到所需内容）
• 高：需要实时查找（Agent 必须搜索）
• 中：有助于提升效率（导航步骤较多）
• 低：锦上添花（改进幅度有限）

3. 干预

根据诊断出的状态：

状态	生成	指导
CN2	关系模板	如何识别关联
CN3	枢纽文档、导航指南	基于任务的组织方式
CN4	CLAUDE.md 优化	如何编写可执行的指令
CN5	依赖关系图模板	影响分析流程
CN6	维护周期文档	更新触发条件、职责

---

回顾整合

接受 context-retrospective 技能的输出：

1. 导入发现：知识缺口、导航问题、指导评估
2. 映射到状态：这些发现表明属于哪个 CN 状态？
3. 确定优先级：使用回顾优先级（Critical/High/Medium/Low）
4. 执行：运行相应的维护模式干预

---

反模式

空架构

模式： 生成完整的目录结构，却让文件为空，或仅包含占位内容。 问题： 没有内容的结构比没有结构更糟——它会让人误以为已有上下文。 解决方法： 只生成用户承诺会填充的结构。从 status.md 和一个领域开始。随着内容积累逐步扩展。

大杂烩

模式： 初始网络试图预判所有可能的需求，采用复杂的分类体系、深层级结构和繁复的元数据。 问题： 维护负担超过了价值。网络变得令人生畏，用户会避免更新。 解决方法： 从精简开始。只有在缺少结构带来实际困扰时才添加结构。初期最多采用两层层级。

孤立的网络

模式： 在最初热情高涨时创建网络，之后再也不更新。status.md 永远停留在过去。 问题： 过时的上下文比没有上下文更糟——Agent 会依据过时信息采取行动。 解决方法： 建立最低限度的维护触发条件：在会话开始和结束时更新 status.md。定期安排回顾。

模板陷阱

模式： 不加调整地使用模板。每个文件都包含相同的章节，无论是否相关。 问题： 样板内容掩盖了实际内容。模板变成了会被跳过的噪声。 解决方法： 模板只是起点，而非要求。删除无关章节，添加项目专属章节。

完整性错觉

模式： 认为网络能够或应该记录一切，不断添加更多细节，希望消除所有缺口。 问题： 信噪比下降。导航变得不可能。维护也难以为继。 解决方法： 聚焦影响重大的缺口。记录 Agent 实际需要的信息。接受有些内容始终需要实时探索。

---

验证（Oracle）

此技能可以验证的内容

• 结构完整性——必需文件是否存在，目录是否齐全
• 链接有效性——交叉引用是否指向存在的目标
• 时效性指标——最后修改日期、更新频率
• 孤立项检测——没有任何传入引用的文件

需要人工判断的内容

• 内容质量——信息是否准确、有用？
• 关系准确性——记录的关联是否反映实际情况？
• 范围是否恰当——网络规模是否适合该项目？
• 导航是否有效——路径是否符合实际使用模式？

---

设计约束

此技能的假设

• 项目能从跨会话的持久上下文中获益
• 用户希望文档能供 Agent 使用
• 某些结构优于完全自由形式的笔记

此技能不处理的内容

• 实时项目工作——转交给：特定领域技能
• 对 Agent 会话进行回顾分析——转交给：context-retrospective
• 框架开发——转交给：skill-builder

能力退化信号

• 用户只想要“一个 README”——可能不需要完整网络
• 项目生命周期少于 1 周——开销可能超过收益
• 纯粹的试验或实验——自由形式的笔记可能更合适

---

输出持久化

输出发现

生成结构之前：

1. 检查是否已存在 .context-network.md
2. 检查是否已存在 context/ 目录
3. 如果是从头开始，请向用户确认目标位置

主要输出

此技能会生成：

• .context-network.md - 发现文件
• context/ 目录结构
• 模板文件（status.md、decisions.md、glossary.md）
• CLAUDE.md 更新（如有需要）

内容归属

写入文件	保留在对话中
目录结构	诊断讨论
模板文件	辅导问答
发现文件	迁移决策
CLAUDE.md 更新	优先级判断依据

---

集成关系图

入站（来自其他技能）

来源技能	触发条件	操作
context-retrospective	发现差距	运行维护模式
skill-builder	新技能需要上下文	运行引导模式

出站（发往其他技能）

触发条件	目标技能	原因
CN4 干预后 Agent 行为问题仍然存在	Review CLAUDE.md patterns	可能需要进行技能级别的更改
网络成熟，需要持续改进	context-retrospective	定期健康检查

互补技能

技能	关系
context-retrospective	事后分析结果可用于维护模式
skill-builder	技能可能需要上下文网络基础设施

---

交互示例

用户：“我正在启动一个新的 TypeScript 项目，想搭建上下文网络。”

你的做法：

1. 扫描现有文档（package.json、README 等）
2. 询问：“主要领域是什么？（例如：API、CLI、库、全栈应用）”
3. 根据回答生成软件项目脚手架
4. 创建 .context-network.md 和 context/ 结构
5. 引导：“从 status.md 开始——项目目前处于什么状态？”