Note-Taking Fundamentals for AI-Assisted Development

Effective note-taking patterns for AI assistants to leave meaningful context in codebases.

Philosophy

When AI assistants make changes to code, they should leave breadcrumbs for future AI assistants and human developers. Notes should:

• Preserve context about why decisions were made
• Signal uncertainty where alternative approaches exist
• Mark incomplete work that needs follow-up
• Link to relevant context (issues, PRs, documentation)
• Explain non-obvious patterns that might confuse readers

Note Formats

AI Development Notes

Special comment format for AI-to-AI communication:

// AI-DEV-NOTE: This function uses a cache-first strategy because
// the data rarely changes and network calls were causing performance
// issues. See performance profiling in PR #123.

# AI-DEV-NOTE: The validation order matters here - we must check
# authentication before authorization to avoid leaking user existence.
# Alternative approach using middleware was considered but rejected
# due to increased complexity.

When to use:

• Explaining non-obvious implementation decisions
• Documenting alternative approaches that were considered
• Linking to related context (PRs, issues, discussions)
• Warning about subtle bugs or edge cases
• Preserving rationale for future refactoring decisions

Structured TODO Comments

Enhanced TODO format with context:

// TODO(ai/context): Extract this validation logic into a separate
// validator class. Currently duplicated in 3 places:
// - src/api/users.ts:45
// - src/api/auth.ts:78
// - src/validators/user.ts:12
// Blocked by: Waiting for PR #456 to merge validator base class

// TODO(ai/performance): This O(n²) loop should be optimized.
// Profiling shows 45% of request time spent here when n > 100.
// Consider: hash map lookup or binary search after sorting.
// Impact: High - affects main user flow
// Effort: Medium - 2-3 hours estimated

TODO Format Structure:

// TODO(ai/<category>): <Brief description>
// <Additional context>
// <Alternative approaches>
// <Blockers/Dependencies>
// <Impact/Priority>

Common categories:

• ai/refactor - Code structure improvements
• ai/performance - Optimization opportunities
• ai/security - Security considerations
• ai/accessibility - A11y improvements
• ai/testing - Test coverage gaps
• ai/docs - Documentation needs
• ai/context - Context preservation
• ai/edge-case - Unhandled edge cases

Decision Records

Inline decision records for significant choices:

// DECISION: Using Arc<RwLock<T>> instead of Mutex<T>
// RATIONALE: Read-heavy workload (95% reads, 5% writes) benefits
// from RwLock's concurrent read access. Benchmarks showed 3x throughput
// improvement with RwLock under typical load patterns.
// ALTERNATIVES_CONSIDERED:
//   - Mutex<T>: Simpler but slower for read-heavy workload
//   - atomic types: Not suitable for complex state
// DATE: 2025-12-04
// AUTHOR: Claude (AI Assistant)

When to use decision records:

• Choosing between competing patterns/libraries
• Performance trade-offs (memory vs speed, etc.)
• Architecture decisions affecting multiple files
• Security-sensitive choices
• Decisions that will be questioned later

Context Preservation

Leaving breadcrumbs for future understanding:

// CONTEXT: This weird-looking workaround is necessary because Safari
// doesn't support the standard API (as of v17.2). Filed webkit bug:
// https://bugs.webkit.org/show_bug.cgi?id=123456
// Remove this when Safari support lands (check caniuse.com)
if (isSafari) {
  // Fallback implementation
}

# CONTEXT: Database migration added 'deleted_at' column (migration_003)
# but we're still using 'is_deleted' for backward compatibility during
# the transition period. Can remove 'is_deleted' after 2025-12-31
# when all old records are migrated.

Uncertainty Markers

Signaling areas where AI is uncertain:

// AI-UNCERTAIN: This might not handle timezone edge cases correctly
// around DST transitions. Manual review recommended by a developer
// familiar with timezone handling.

// AI-UNCERTAIN: Not sure if this is thread-safe in all scenarios.
// Consider adding synchronization or having a concurrency expert review.

Note Placement Guidelines

Where to Place Notes

Good placements:

// AI-DEV-NOTE: Complex business logic follows - this implements the
// three-tier approval workflow described in docs/workflows.md
function processApproval(request: ApprovalRequest) {
  // Implementation...
}

Bad placements:

function processApproval(request: ApprovalRequest) {
  const step1 = validate(request);
  // AI-DEV-NOTE: This whole function is complex
  const step2 = process(step1);
  // Bad - note is buried in implementation details
}

Proximity Rules

• Place notes immediately before the code they describe
• For file-level notes, place at the top after imports
• For function-level notes, place immediately before the function
• For inline notes, place on the line above the relevant code

Note Density

Avoid over-annotation:

// ❌ TOO MANY NOTES
// AI-DEV-NOTE: Parsing user input
const input = parseInput(raw);
// AI-DEV-NOTE: Validating the input
const valid = validate(input);
// AI-DEV-NOTE: Processing the result
const result = process(valid);

// ✅ APPROPRIATE DENSITY
// AI-DEV-NOTE: Standard validation pipeline - parse, validate, process
// Each step can throw ValidationError which is handled by middleware
const input = parseInput(raw);
const valid = validate(input);
const result = process(valid);

Cross-Referencing

Linking to Issues/PRs

// AI-DEV-NOTE: Implements user story from issue #1234
// See PR #1245 for discussion on alternative approaches

Linking to Documentation

# AI-DEV-NOTE: Algorithm explained in docs/algorithms/rate-limiting.md
# Based on token bucket algorithm: https://en.wikipedia.org/wiki/Token_bucket

Linking to Other Code

// AI-DEV-NOTE: Mirror of validation logic in api/v2/handlers.go:123
// Keep these in sync or extract to shared validator

Note Maintenance

Expiration Dates

For temporary notes or workarounds:

// AI-DEV-NOTE: Temporary workaround for API v1 compatibility
// REMOVE_AFTER: 2025-12-31 (when v1 API is fully deprecated)

# TODO(ai/temporary): Using placeholder implementation
# REPLACE_WHEN: Real authentication service is deployed

Note Updates

When modifying code with existing notes:

// AI-DEV-NOTE: [UPDATED 2025-12-04] Originally used synchronous
// processing but switched to async to prevent UI blocking.
// Previous note preserved for context.
// [ORIGINAL 2025-11-15] This processes items synchronously...

Anti-Patterns

Don't

❌ Leave vague notes

// AI-DEV-NOTE: This is important
// Bad - no context about WHY it's important

❌ Over-explain obvious code

# AI-DEV-NOTE: This increments the counter by 1
count += 1  # Obvious from code

❌ Leave notes without actionable information

// TODO: Fix this
// Bad - no context on WHAT needs fixing or HOW

❌ Duplicate information already in commit messages

// AI-DEV-NOTE: Added error handling
// Bad - commit message already says this

Do

✅ Provide specific, actionable context

// AI-DEV-NOTE: Order validation must happen before inventory check
// to prevent race condition where items are reserved but invalid

✅ Explain the "why" not the "what"

# AI-DEV-NOTE: Using binary search instead of linear search because
# the dataset can exceed 10k items (profiling showed 300ms avg latency)

✅ Include concrete next steps

// TODO(ai/refactor): Extract duplicate validation into shared validator
// Files to update: api/users.ts, api/teams.ts, api/projects.ts
// Estimated effort: 1-2 hours

✅ Link to external context

// AI-DEV-NOTE: Implements RFC 6749 OAuth 2.0 Authorization Framework
// https://tools.ietf.org/html/rfc6749#section-4.1

Examples by Language

TypeScript/JavaScript

/**
 * AI-DEV-NOTE: This function uses a debounced approach to avoid
 * excessive API calls during rapid user input. The 300ms delay
 * was determined through user testing to balance responsiveness
 * with server load. See analytics dashboard for metrics.
 *
 * TODO(ai/performance): Consider implementing request cancellation
 * for in-flight requests when user continues typing. Currently
 * we rely on server-side deduplication which isn't ideal.
 */
export function searchUsers(query: string): Promise<User[]> {
  // Implementation...
}

Python

# AI-DEV-NOTE: This class implements the Repository pattern to
# abstract database access. All database operations should go
# through repository methods to maintain consistency and enable
# easier testing with mock repositories.
#
# DECISION: Using async/await throughout because:
# 1. Database I/O is inherently async
# 2. Allows concurrent operations for bulk updates
# 3. Prevents blocking the event loop in FastAPI
#
# Alternative (sync SQLAlchemy) was rejected because it would
# require running in thread pools which adds complexity.

class UserRepository:
    def __init__(self, db: AsyncSession):
        self.db = db

    # TODO(ai/caching): Add Redis caching layer for frequently
    # accessed users (identified from logs: user profile views
    # account for 40% of DB queries). Estimated impact: 60% reduction
    # in database load. Blocked by: Redis infrastructure setup
    async def get_by_id(self, user_id: int) -> Optional[User]:
        # Implementation...
        pass

Go

// AI-DEV-NOTE: This middleware implements request tracing using
// OpenTelemetry. Each request gets a unique trace ID that flows
// through the entire request lifecycle, making debugging distributed
// systems much easier.
//
// CONTEXT: We chose OpenTelemetry over custom tracing because:
// - Industry standard with wide tool support
// - Compatible with Jaeger, Zipkin, and cloud providers
// - Lower maintenance burden than custom solution
//
// Configuration is in config/telemetry.yaml
func TracingMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        // AI-UNCERTAIN: The sampling rate (10%) might be too low
        // for debugging rare issues. Consider dynamic sampling
        // based on error rates or request patterns. Needs monitoring
        // data to make informed decision.

        // Implementation...
    }
}

Rust

// AI-DEV-NOTE: This implementation uses unsafe code to achieve
// zero-copy parsing. The safety invariants are:
// 1. Input buffer must outlive all returned references
// 2. No mutable aliases can exist during parsing
// 3. UTF-8 validity is checked before transmutation
//
// SAFETY: These invariants are maintained because:
// - Buffer is borrowed for 'a lifetime (enforced by type system)
// - Parser is consumed during parsing (no mutable aliases possible)
// - from_utf8_unchecked is only called after validation
//
// TODO(ai/safety): Consider adding fuzzing tests to validate
// safety assumptions under malformed input. Current test coverage
// is good for valid input but edge cases might break invariants.
unsafe fn parse_str<'a>(buf: &'a [u8]) -> Result<&'a str, ParseError> {
    // Implementation...
}

Integration with Development Workflow

Pre-Commit Review

Before committing, AI should review notes:

1. Ensure all AI-UNCERTAIN notes have corresponding test coverage
2. Check that TODO(ai/*) notes have enough context for follow-up
3. Verify links to issues/PRs are valid
4. Remove or update outdated notes

Note Extraction

Teams can extract AI notes for review:

# Find all AI development notes
grep -r "AI-DEV-NOTE" src/

# Find all AI TODOs
grep -r "TODO(ai/" src/

# Find uncertain areas needing review
grep -r "AI-UNCERTAIN" src/

Note Analytics

Track note patterns to improve AI assistance:

• Density of AI-UNCERTAIN notes (indicates confidence)
• Categories of TODO(ai/*) notes (indicates common issues)
• Age of notes (indicates maintenance burden)

Related Skills

• code-annotation-patterns
• documentation-linking

Resources

• AI-Powered Documentation: Make Your Codebase Self-Explanatory
• Top 2025 AI Documentation Tools to Boost Developer Productivity
• AI for Code Documentation: Essential Tips