SuperAPI AI Directory

build-cognitive-context

General & other

View repository

Updated 10-16 09:44

About this skill

Context — Context Engineering

Entry/Exit

  • Entry: Before starting a new task, when the context window is mixed, when agent output quality degrades, when switching projects
  • Exit: Clean and correct context + all necessary task-relevant information
  • Points to: Continue the current build flow
  • Output path: The build skill currently being executed (e.g. build-workflow-execute)
  • Preload: CANON.md

When not to use

  • The task is a clear, self-contained one-line change (white screen/null pointer fix)
  • The conversation has just started and the problem description is extremely precise

Iron Law

上下文质量是 agent 输出质量的最大杠杆。
更多上下文 ≠ 更好上下文。
上下文窗口大小 ≠ 注意力预算。

Five-level context hierarchy

Load by priority — upper levels first, lower levels on demand:

Level 1: 规则文件
  AGENTS.md / CANON.md / .cursorrules
  → 始终加载。定义全局行为和宪法纪律。
  
Level 2: 规格说明
  docs/features/YYYYMMDD-<name>/01-spec.md / 02-design.md / 03-plan.md
  → 当前任务需要时加载。定义"做什么"。
  
Level 3: 源代码
  相关文件 / 接口定义 / 类型声明
  → 仅在需要理解现有代码时加载。定义"怎么做"。
  
Level 4: 错误输出
  测试失败日志 / 构建错误 / lint 警告
  → 仅在调试或验证时加载。定义"什么错了"。
  
Level 5: 对话历史
  先前讨论 / 中间决策 / 已排除方案
  → 引用结论,不复述全过程。定义"什么已决定"。

Context packing strategies

Strategy Method Applicable
Brain Dump Load all relevant files at once Small projects (< 50 files), exploration phase
Selective Include Load only files directly relevant to the task Regular tasks (default)
Hierarchical Summary Hierarchical summary (architecture→module→file) Large projects, cross-module refactoring

Use Selective Include by default. Brain Dump wastes tokens and attention. Hierarchical Summary is costly.

Confusion management

When contexts conflict with each other

STOP。不要在混淆中前进。

1. 识别冲突: "spec 说 X,但现有代码做的是 Y"
   ✅ 验证点: 冲突是否已明确写出到 human partner?
2. 明确选项: "选项 A: 按 spec 重构(需要 X 小时)。选项 B: 更新 spec(已和用户确认这是旧 spec)"
   ✅ 验证点: 两个选项是否包含时间/影响估算?
3. 呈现权衡: "选 A 意味着 XX。选 B 意味着 YY"
   ✅ 验证点: human partner 是否已做出明确选择?
4. 等待用户决定。不猜。

When requirements are incomplete

Do not silently assume to fill in the gaps. Expose the gaps:

"需求说'让仪表盘更快',但没指定:
1. 目标 LCP 是多少?(2.5s 是 Core Web Vitals 标准)
2. 什么网络条件?(4G?WiFi?)
3. 包括 SSR 时间吗?

我假设:目标 LCP < 2.5s(4G 网络),不包括 SSR。
→ 纠正我,否则我按这些继续。"

When there is implicit knowledge

If the project follows non-standard conventions but they are not documented → document them:

"我刚发现这个项目用 Prisma 而不是 TypeORM(虽然同类项目都用的 TypeORM)。
这不在 AGENTS.md 里。让我记下来避免下次混淆。"

Then write the findings into AGENTS.md.

Anti-patterns

Anti-pattern Symptom Fix
Context starvation Agent guesses API behavior, invents interfaces on its own Load relevant source code or documentation
Context flooding 20+ files loaded but only 1 changed Trim to the files actually needed
Stale context Uses deleted functions/deprecated APIs Re-read the files, do not rely on memory
Missing examples The patterns the agent writes differ from existing consistent code in the project Find a working example in the project as a reference
Implicit knowledge Project conventions are not written in any documentation Write them into AGENTS.md
Silent confusion The agent finds an inconsistency but does not say so Enforce Article 8 of the constitution

Common excuses

Excuse Reality Consequence
"I have already looked at this file" The file may have changed. Re-read the key parts. Coding based on stale context → introduces bugs or conflicts with deleted APIs, wasting an average of 30-60 minutes debugging
"Loading more is always better than loading less" Context flooding dilutes attention. Selectively loading target information is more effective. Only 1 change across 20+ files → 90%+ of tokens go to irrelevant content, key details get drowned out, and decision quality drops
"I know how to use this library" Different versions have different APIs. Trust the documentation, not memory. Using a deprecated API → runtime crash or silent behavior differences, 1-4 hours of rework per occurrence

Validation Failure Handling

Failure Scenario Handling Method
spec not loaded Stop the task and first load the current feature's 01-spec.md before continuing
Key source code inferred from memory rather than read Force re-reading of the relevant files; using "I remember" as a basis is prohibited
spec and code conflict and no clarification has been made List the conflict points and two options, and wait for the human partner to decide before continuing
Ambiguous requirement not raised for clarification List the gaps one by one with default assumptions, and wait for the human partner to correct or confirm
Non-standard project convention not recorded Immediately write to AGENTS.md and note the discovery time to avoid confusion next time

Good and Bad Examples

✅ Good: Selective loading + make conflicts explicit

任务: 修改 TaskList 组件的筛选逻辑

加载策略: Selective Include
- Level 1: AGENTS.md(始终)
- Level 2: 01-spec.md(筛选逻辑规格)
- Level 3: TaskList.tsx / TaskList.test.tsx / filterUtils.ts(只这 3 个)
- Level 5: 上次讨论结论 "筛选应支持多条件组合"

发现冲突: spec 说"筛选条件互斥",但现有代码支持组合筛选。
→ 向 human partner 呈现两个选项,等待决定。

❌ Bad: Full loading + implicit assumptions

任务: 修改 TaskList 组件的筛选逻辑

加载策略: Brain Dump(读了 25 个文件)
→ 关键信息被淹没,注意力浪费在无关组件上

发现冲突: spec 和代码不一致,但默默选择"按代码改"。
→ 没有向 human partner 澄清,后续实现偏离 spec。

Red Flags — STOP

  • Starting implementation without checking the existing code
  • Discovering a conflict between spec and code but silently continuing
  • Seeing a strange convention ("Why is it written like this?") but neither asking nor recording it
  • Re-reading the same file over and over without making progress
  • Using "this is the usual way" instead of "what the project actually uses is X"

Output Template

After context organization is complete, the following structure should be produced (written into a checkpoint or the task start comment):

## Context Summary — [任务名称]

### 加载策略
- 策略类型: [Brain Dump / Selective Include / Hierarchical Summary]
- 已加载文件: [文件列表]
- 跳过文件及原因: [跳过列表]

### 已识别冲突
| # | 冲突描述 | 选项 A | 选项 B | 决定 |
|---|---------|--------|--------|------|
| 1 | ... | ... | ... | [待定 / 已决定] |

### 需澄清缺口
| # | 缺口描述 | 默认假设 | 确认状态 |
|---|---------|---------|---------|
| 1 | ... | ... | [待确认 / 已确认] |

### 新发现的项目约定
| # | 约定描述 | 写入位置 |
|---|---------|---------|
| 1 | ... | AGENTS.md |

Validation Checklist

  • The AGENTS.md/spec relevant to the current task has been loaded (detailed runtime rules are in docs/contracts/ , read on demand)
  • Key source code files have been read (not inferred from memory)
  • Any conflicts (spec vs code) have been identified and resolved
  • Unclear points in ambiguous requirements have been raised to the user for clarification
  • Newly discovered project conventions have been written into AGENTS.md