documentation-linking

Use when creating bidirectional links between code and documentation. Covers link patterns, documentation references, context preservation across artifacts, and maintaining synchronization between code and docs.

⭐47stars🔀5forks📁View on GitHub🕐Updated Jan 2, 2026⬇️2downloads

When & Why to Use This Skill

This Claude skill facilitates the creation and maintenance of bidirectional links between source code and technical documentation. By implementing standardized link patterns and synchronization strategies, it ensures that architecture designs, API specifications, and decision records remain perfectly aligned with the implementation. It is designed to eliminate documentation rot, enhance codebase navigability, and preserve critical context across various development artifacts in AI-assisted workflows.

Use Cases

  • Architecture Traceability: Establishing direct links between complex service implementations and their corresponding Architecture Decision Records (ADRs) or system diagrams to explain the rationale behind specific code structures.
  • API Contract Synchronization: Connecting REST/GraphQL endpoints directly to OpenAPI or Swagger specifications, ensuring that the code implementation and the published API documentation never diverge.
  • Automated Link Validation: Implementing pre-commit hooks and validation scripts to automatically detect and fix broken documentation links, maintaining the integrity of the knowledge base during rapid development cycles.
  • Operational Readiness: Linking critical infrastructure-as-code or monitoring logic to incident response runbooks, allowing SREs and DevOps engineers to access troubleshooting steps instantly during system alerts.
  • Developer Onboarding: Creating a self-documenting codebase where new team members can navigate from high-level tutorials and READMEs directly to the relevant implementation files and vice versa.
namedocumentation-linking
descriptionUse when creating bidirectional links between code and documentation. Covers link patterns, documentation references, context preservation across artifacts, and maintaining synchronization between code and docs.

Documentation Linking

Creating and maintaining bidirectional links between code and documentation for AI-assisted development.

Bidirectional Linking

Code → Documentation

Link from code to relevant documentation:

/**
 * Implements the authentication flow described in:
 * @doc docs/architecture/authentication.md#oauth-flow
 * @api-spec api/openapi.yaml#/components/securitySchemes/oauth2
 * @decision-record docs/decisions/003-oauth-provider.md
 *
 * Related endpoints:
 * - POST /auth/login (login initiation)
 * - GET /auth/callback (OAuth callback)
 * - POST /auth/refresh (token refresh)
 */
export class AuthenticationService {
  // Implementation
}

Documentation → Code

Link from documentation to implementing code:

# Authentication Flow

Our OAuth 2.0 authentication flow is implemented in:

- Main logic: `src/services/AuthenticationService.ts`
- Routes: `src/routes/auth.ts:15-45`
- Middleware: `src/middleware/auth.ts:78`
- Tests: `tests/integration/auth.test.ts`

See also:
- Database schema: `migrations/003_create_users.sql`
- Configuration: `config/auth.yaml`
# @doc /docs/database/migrations.md#schema-versioning
# Full path from repository root
// @doc ../../../docs/api/rest-endpoints.md#user-endpoints
// Relative to current file
// @impl service/user_service.go:145-178
// Links to specific line range
/// @doc architecture.md#data-flow-diagram
/// Links to specific section via anchor

Documentation Types

Architecture Documentation

/**
 * @arch-doc docs/architecture/system-overview.md
 * @component-diagram docs/diagrams/user-service.svg
 * @sequence-diagram docs/diagrams/login-flow.puml
 *
 * This service is part of the user management subsystem.
 * See architecture docs for component interactions and data flow.
 */
class UserService {
  // Implementation
}

API Documentation

# @api-doc docs/api/rest-api.md#POST-/users
# @openapi-spec api/openapi.yaml#/paths/~1users/post
# @example docs/examples/create-user.md
#
# REST endpoint for creating users. API contract is defined in OpenAPI spec.
# Changes to request/response format must update both code and spec.

@app.post("/users")
async def create_user(user: UserCreate) -> User:
    """
    @request-example:
      POST /users
      {
        "email": "user@example.com",
        "name": "John Doe"
      }

    @response-example:
      201 Created
      {
        "id": 123,
        "email": "user@example.com",
        "name": "John Doe",
        "created_at": "2025-12-04T10:00:00Z"
      }
    """
    # Implementation

Decision Records

/**
 * @decision-record docs/decisions/005-caching-strategy.md
 *
 * DECISION: Using Redis for caching instead of in-memory cache
 * RATIONALE: Need distributed cache for horizontal scaling
 * DATE: 2025-11-15
 *
 * This implements the caching strategy defined in ADR-005.
 * Cache invalidation rules:
 * 1. Time-based: 5 minute TTL
 * 2. Event-based: Invalidate on user.updated event
 * 3. Manual: Admin can clear cache via /admin/cache/clear
 */
public class CacheService {
    // Implementation following decision record
}

Test Documentation

// @test-doc docs/testing/integration-tests.md#database-tests
// @test-data fixtures/users.json
// @test-cases tests/integration/user_test.go
//
// Integration tests use Docker containers for PostgreSQL.
// Test data is loaded from fixtures before each test.
// See test documentation for setup instructions.

func TestUserRepository(t *testing.T) {
    // Test implementation
}
# @runbook docs/runbooks/incident-response.md#database-failover
# @monitoring dashboard/database-health
# @alerts alerts/database-connection-pool
#
# Database connection pool monitoring and failover logic.
# If pool exhaustion alert fires, follow runbook for mitigation steps.

class DatabaseConnectionPool:
    """
    @metric connection_pool_active (gauge)
    @metric connection_pool_idle (gauge)
    @metric connection_pool_wait_time (histogram)

    Alert thresholds:
    - connection_pool_active > 90% of max_connections for 5min
    - connection_pool_wait_time p95 > 1000ms
    """
    # Implementation

Cross-Referencing Patterns

Issue/Ticket References

/**
 * @issue https://github.com/org/repo/issues/1234
 * @pr https://github.com/org/repo/pull/1245
 * @jira PROJ-567
 *
 * Implements user story PROJ-567: Real-time notification system
 * See issue #1234 for requirements discussion
 * See PR #1245 for implementation review and feedback
 */
class NotificationService {
  // Implementation
}
# @wiki https://wiki.company.com/display/ENG/Data+Pipeline
# @confluence https://company.atlassian.net/wiki/spaces/ARCH/pages/123456
#
# Data pipeline architecture documented in company wiki.
# This implements the extraction phase of the ETL pipeline.

class DataExtractor:
    # Implementation

External Resources

/// @rfc https://tools.ietf.org/html/rfc7519
/// @spec https://openid.net/specs/openid-connect-core-1_0.html
/// @tutorial https://auth0.com/docs/secure/tokens/json-web-tokens
///
/// JWT implementation following RFC 7519 specification.
/// Supports OpenID Connect extensions per OIDC Core spec.

pub struct JwtToken {
    // Implementation
}

Synchronization Strategies

Script to validate documentation links:

#!/bin/bash
# validate-doc-links.sh

# Extract all @doc references from code
grep -r "@doc " src/ | while read -r line; do
  doc_path=$(echo "$line" | sed -n 's/.*@doc \([^[:space:]]*\).*/\1/p')
  file_path=$(echo "$doc_path" | cut -d'#' -f1)

  if [ ! -f "$file_path" ]; then
    echo "ERROR: Broken doc link: $doc_path"
    echo "  Referenced in: $line"
  fi
done

Documentation Coverage

Track which code has documentation links:

# doc-coverage.py
import re
from pathlib import Path

def has_doc_link(file_path):
    """Check if file contains @doc annotations"""
    with open(file_path) as f:
        content = f.read()
    return '@doc' in content or '@api-doc' in content

# Calculate coverage
source_files = list(Path('src').rglob('*.py'))
with_docs = [f for f in source_files if has_doc_link(f)]
coverage = len(with_docs) / len(source_files) * 100

print(f"Documentation link coverage: {coverage:.1f}%")

Maintain reverse index in documentation:

# Authentication Documentation

## Referenced By

This document is referenced by the following code files:

- `src/services/AuthenticationService.ts:15` - Main auth logic
- `src/middleware/auth.ts:34` - Auth middleware
- `src/routes/auth.ts:8` - Auth routes

<!-- AUTO-GENERATED: Do not edit manually -->
<!-- Generated by: scripts/update-doc-references.sh -->

Automated Updates

Git pre-commit hook to check doc links:

#!/bin/bash
# .git/hooks/pre-commit

echo "Validating documentation links..."

# Check for broken @doc links
broken_links=$(grep -r "@doc " src/ | while read -r line; do
  doc_path=$(echo "$line" | sed -n 's/.*@doc \([^[:space:]]*\).*/\1/p')
  file_path=$(echo "$doc_path" | cut -d'#' -f1)

  if [ ! -f "$file_path" ]; then
    echo "$line"
  fi
done)

if [ -n "$broken_links" ]; then
  echo "ERROR: Broken documentation links found:"
  echo "$broken_links"
  exit 1
fi

Mark outdated links:

/**
 * @doc docs/old-approach.md [DEPRECATED: See docs/new-approach.md]
 * @doc-current docs/new-approach.md
 *
 * This implementation is being migrated to new approach.
 * Old documentation kept for reference during transition.
 * Migration deadline: 2026-01-01
 */

Versioned Documentation

Link to specific documentation versions:

# @doc docs/v2/api-reference.md
# @doc-version 2.3.0
#
# This code implements API v2.3.0 specification.
# For v3.0.0 changes, see docs/v3/migration-guide.md

class APIv2Handler:
    # Implementation

Documentation Patterns

Link to README for module documentation:

// @readme ./README.md
//
// Package userservice provides user management functionality.
// See README.md for usage examples and configuration options.

package userservice

Example Code

Link to runnable examples:

/// @example examples/basic-usage.rs
/// @example-advanced examples/advanced-patterns.rs
///
/// Basic usage example shows simple CRUD operations.
/// Advanced example demonstrates batching and transactions.

pub struct Repository<T> {
    // Implementation
}
/**
 * @tutorial docs/tutorials/getting-started.md
 * @tutorial-video https://youtube.com/watch?v=abc123
 * @interactive-demo https://demo.example.com
 *
 * New to this library? Start with the getting started tutorial.
 * Video walkthrough available for visual learners.
 */
export class SDK {
  // Implementation
}

Anti-Patterns

Don't

❌ Use brittle relative links

# @doc ../../../../../../../docs/guide.md
# Bad - breaks easily when files move

❌ Link to outdated documentation

// @doc docs/deprecated-api.md
// Bad - should link to current docs or mark as deprecated

❌ Create circular documentation dependencies

// file1.go
// @doc docs/file2.md

// docs/file2.md references file3.go
// file3.go references file1.go
// Bad - circular reference makes navigation confusing

Do

✅ Use repository-relative paths

# @doc docs/guide.md
# Good - stable even if current file moves

✅ Keep links current

// @doc docs/current-api.md
// @doc-history docs/api-v1.md [DEPRECATED]
// Good - clear which is current

✅ Create clear navigation hierarchy

// @doc-parent docs/architecture/overview.md
// @doc-current docs/architecture/auth-service.md
// @doc-related docs/architecture/user-service.md
// Good - clear hierarchy and relationships

Integration Examples

Markdown Documentation

# User Service

## Implementation

The user service is implemented across several files:

### Core Logic

- [`src/services/UserService.ts`](../src/services/UserService.ts) - Main service class
- [`src/models/User.ts`](../src/models/User.ts) - User model
- [`src/repositories/UserRepository.ts`](../src/repositories/UserRepository.ts) - Data access

### API Layer

- [`src/routes/users.ts`](../src/routes/users.ts#L15-L45) - REST endpoints
- [`src/controllers/UserController.ts`](../src/controllers/UserController.ts) - Request handling

### Tests

- [`tests/unit/UserService.test.ts`](../tests/unit/UserService.test.ts) - Unit tests
- [`tests/integration/users.test.ts`](../tests/integration/users.test.ts) - Integration tests

OpenAPI/Swagger

# api/openapi.yaml
paths:
  /users:
    post:
      summary: Create user
      description: |
        Creates a new user in the system.

        **Implementation:**
        - Handler: `src/handlers/users.go:CreateUser`
        - Validation: `src/validators/user.go:ValidateCreate`
        - Database: `src/repositories/user_repo.go:Insert`

        **Related Documentation:**
        - [User Management Guide](../docs/user-management.md)
        - [API Authentication](../docs/api-auth.md)

JSDoc/TypeDoc

/**
 * User authentication service
 *
 * @see {@link ../docs/architecture/auth-flow.md} for authentication flow diagram
 * @see {@link ../docs/api/auth-api.md} for API documentation
 *
 * @example
 * ```typescript
 * const auth = new AuthService();
 * const token = await auth.login(username, password);
 * ```
 *
 * @example
 * See {@link ../examples/auth-flow.ts} for complete authentication example
 */
export class AuthService {
  // Implementation
}
  • notetaker-fundamentals
  • code-annotation-patterns

Resources