self-commenting

petbrains 的头像作者 petbrains

具有 grep 可搜索的 AICODE-* 标记的 AI 原生代码注释系统,用于跨会话记忆。在处理代码文件、为未来会话留下笔记、分解复杂任务、记录非显而易见的逻辑、记录错误修复时使用。触发于:开始编码会话、编辑代码、复杂逻辑、留下笔记、稍后待办、调试会话、错误修复、AICODE 标记、自我注释。

📖 中文导读:具有 grep 可搜索的 AICODE-* 标记的 AI 原生代码注释系统,用于跨会话记忆。在处理代码文件、为未来会话留下笔记、分解复杂任务、记录非显而易见的逻辑、记录错误修复时使用。触发于:开始编码会话、编辑代码、复杂逻辑、留下笔记、稍后待办、调试会话、错误修复、AICODE 标记、自我注释。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: self-commenting description: AI-native code commenting system with grep-searchable AICODE-* markers for cross-session memory. Use when: working with code files, leaving notes for future sessions, breaking down complex tasks, documenting non-obvious logic, recording bug fixes. Triggers: start coding session, edit code, complex logic, leave note, todo for later, debug session, bug fix, AICODE markers, self-commenting. allowed-tools: Read, Write, Bash(grep:*)

Self-Commenting

Long-term memory layer in code using grep-searchable AICODE-* markers.

Process

SCAN → WORK → ANNOTATE

Step 1: Scan

Before modifying any file, find existing markers:

grep -rn "AICODE-" <file-or-directory>

Read markers to understand previous context and pending tasks.

Step 2: Work

Edit code normally.

Step 3: Annotate

Add markers for cross-session memory:

  • AICODE-NOTE — critical implementation details
  • AICODE-TODO — pending tasks to complete
  • AICODE-FIX — non-trivial bug solutions (problem → cause → fix)

See references/conventions.md for format, language syntax, and examples.

Decision Rules

Add AICODE-NOTE when:

  • Non-obvious algorithm or approach
  • External API constraints
  • Complex state management
  • Integration quirks

Add AICODE-TODO when:

  • Task out of current scope
  • Needs more information
  • Depends on other work

Add AICODE-FIX when:

  • Bug solution was non-trivial
  • Root cause wasn't obvious
  • Similar bugs might occur elsewhere

Skip markers when:

  • Code is self-explanatory
  • Standard pattern usage
  • Trivial one-line fix

Session Workflow

Start: grep -rn "AICODE-" src/

Before debugging: Check for similar AICODE-FIX in codebase

End: Add TODO for incomplete work, NOTE for key decisions, FIX for solved bugs