self-commenting

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.

⭐4stars🔀0forks📁View on GitHub🕐Updated Dec 22, 2025⬇️1downloads

When & Why to Use This Skill

The Self-Commenting skill is an AI-native code annotation system designed to establish a long-term memory layer within your codebase. By utilizing grep-searchable AICODE-* markers, it enables AI agents to maintain context across different sessions, document complex logic, and track pending tasks. This skill effectively solves the problem of context loss in AI-assisted development, ensuring that critical implementation details and bug fix histories are preserved and easily retrievable for future coding sessions.

Use Cases

  • Cross-Session Task Management: Use AICODE-TODO markers to flag incomplete features or pending refactors, allowing the AI to resume work exactly where it left off in a new session.
  • Documenting Complex Logic: Apply AICODE-NOTE to explain non-obvious algorithms, external API constraints, or intricate state management that might be misinterpreted by AI in future interactions.
  • Bug Fix Knowledge Base: Record non-trivial bug solutions using AICODE-FIX (problem → cause → fix) to provide a searchable history that prevents the reintroduction of similar issues.
  • Architectural Context Preservation: Maintain a record of high-level architectural decisions and integration quirks directly in the source files to guide future code generation and reviews.
  • AI-Human Collaboration: Create a standardized communication channel within the code where the AI agent leaves notes for human developers regarding technical debt or specific implementation choices.
nameself-commenting
descriptionAI-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-toolsRead, 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