AgentSkillsCN

cognitive-debt-guard

在 AI 辅助开发过程中有效避免认知债务累积。无论是在进行代码变更、功能开发、重构，还是执行任何 AI 辅助编码任务时——尤其是在多轮会话的项目中——都可随时启用此技能。当用户提出诸如“从上次中断的地方继续”、“接续上一节的内容”、“实现这个功能”或“构建这个模块”等需求时，此技能便会自动触发。它能够帮助人类在整个 AI 辅助开发过程中，始终保有对系统清晰而完整的心理模型，从而避免因对自身代码库失去理性思考能力而导致团队与个人陷入停滞的“隐性理论流失”困境。

SKILL.md
--- frontmatter
name: cognitive-debt-guard
description: >
  Prevents cognitive debt accumulation during AI-assisted development sessions.
  Use this skill whenever working on code changes, feature development, refactoring,
  or any AI-assisted coding task -- especially in multi-session projects. Triggers on
  any coding request, feature implementation, bug fix, or architecture change.
  Also triggers when the user says things like "continue where we left off",
  "pick up from last session", "implement this feature", or "build this".
  This skill ensures the human maintains a working mental model of the system
  throughout AI-assisted development, preventing the silent loss of shared theory
  that paralyzes teams and individuals when they can no longer reason about their
  own codebase.

Cognitive Debt Guard

What This Skill Does

This skill enforces a protocol that keeps the human developer's understanding in sync with the code being produced. It does NOT slow down development. It changes the sequence of operations so that understanding is built as a first-class output alongside the code.

The core principle: velocity without understanding is not sustainable velocity. Code that works but that nobody can explain, modify, or reason about is a liability, not an asset.

Background: What Is Cognitive Debt?

Read references/cognitive-debt-primer.md for the full theoretical background.

Short version: Technical debt lives in the code. Cognitive debt lives in the developer's brain. It accumulates when AI tools produce code faster than the human builds understanding of that code. The result is a developer (or team) who built a system they cannot confidently modify, debug, or extend.

Session Protocol

Every coding session follows this sequence. Do not skip steps.

1. Session Startup Check

Before writing any code, check for and read the project's DEVLOG.md. If it exists, read the most recent entry. This is the previous session's "save state."

If no DEVLOG.md exists, create one from the template in assets/templates/DEVLOG-template.md.

Ask the developer: "What's your current mental model of how this part of the system works?" If they can articulate it clearly, proceed. If they hesitate or are vague, spend time rebuilding understanding before writing new code.

2. Theory-First Implementation

For every task, require the developer to state the design intention BEFORE you generate code. Not a prompt. A hypothesis:

  • •What should change in the system's behavior?
  • •Why this approach over alternatives?
  • •What existing parts of the system does this interact with?

If the developer says "just do it" or "you figure it out," push back gently. Offer to explain the options and let them choose. The choice itself builds understanding. The AI making the choice silently is where cognitive debt starts.

3. Small, Reviewable Increments

Never implement an entire feature in one pass. Break every task into pieces where each piece:

  • •Changes fewer than ~5 files
  • •Introduces one new concept or abstraction
  • •Can be explained in 2-3 sentences
  • •Can be tested or verified independently

After each increment, pause and narrate what was done and why. Ask the developer to confirm their understanding before proceeding to the next piece.

4. Decision Logging

Every time you (the AI) make a non-trivial design choice, explicitly call it out and log it. Non-trivial means:

  • •Choosing between data structures
  • •Picking an error handling strategy
  • •Selecting a dependency or library
  • •Designing an API shape or interface
  • •Choosing an architectural pattern

Format each decision as a one-liner and append it to DECISION-LOG.md in the project root. If the file does not exist, create it from the template in assets/templates/DECISION-LOG-template.md.

5. Session Wrap-Up

At the end of every session (or when the developer signals they are done), create a DEVLOG entry covering:

  • •What changed (human narrative, not a git log)
  • •What design decisions were made and why
  • •What is still uncertain or incomplete
  • •What the next session should start with

Also generate a commit message that captures the WHY, not just the WHAT. "Add Redis session backend to survive server restarts" not "Add Redis sessions."

6. Periodic Theory Checks

If a session has been running for a long time (many tool calls, many files changed), pause and run a theory check:

  • •"Can you walk me through how [subsystem] works now?"
  • •"What would you change if requirement X shifted?"
  • •"What are the key invariants this code depends on?"

If the developer struggles with these questions, stop adding features and spend time on understanding. This is NOT a slowdown. This is preventing the much larger slowdown that comes from cognitive debt compounding.

What To Do When The Developer Pushes Back

Developers under deadline pressure will want to skip these steps. That is understandable. The skill should be firm but not annoying.

  • •If they skip session startup: Proceed, but note that you are working without a verified mental model and flag this at wrap-up.
  • •If they skip theory-first: Offer two implementation approaches and ask them to pick. This is faster than writing the hypothesis but still builds understanding through choice.
  • •If they skip decision logging: Log decisions yourself in your responses so the information exists in the conversation history at minimum.
  • •If they skip session wrap-up: Generate the DEVLOG entry yourself and present it for their review.

The non-negotiable minimum is: the developer must be able to explain what changed and why after every session. Everything else is a means to that end.

Integration with Other Tools

This skill generates artifacts that work with other AI coding tools. Read references/cross-tool-enforcement.md for details on:

  • •CLAUDE.md (Claude Code)
  • •GEMINI.md (Gemini CLI)
  • •AGENTS.md (Google Jules)
  • •.github/copilot-instructions.md (GitHub Copilot)
  • •.cursorrules (Cursor)
  • •.windsurfrules (Windsurf)
  • •CONVENTIONS.md + .aider.conf.yml (Aider)
  • •Git hooks for process enforcement
  • •PR templates with theory checks

Run scripts/setup-enforcement.sh to install all enforcement files into a project repository.

File Templates

All templates are in assets/templates/:

  • •DEVLOG-template.md - Session journal template
  • •DECISION-LOG-template.md - Design decision tracking
  • •PR-TEMPLATE.md - Pull request template with theory checks
  • •COMMIT-MSG-TEMPLATE.txt - Commit message format guide