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.
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.
| 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 detailsAICODE-TODO— pending tasks to completeAICODE-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