doc-sync（文档同步）

Doc Sync

Update documentation to reflect recent code changes. Validates and ensures documentation stays synchronized with code.

When to use this skill

• After making code changes that affect architecture or APIs
• When documentation may be out of sync with code
• During code review to verify documentation completeness
• To check for broken links in documentation
• When setting up documentation validation in a repository
• When asked to "sync docs" or "update documentation"

Skill Contents

Sections

• When to use this skill
• Quick Start
• Documentation Validation Checks
• Integration with RFC-37
• Pre-Push Documentation Check
• Available Functions
• Documentation Tools by Project Type
• Best Practices
• References
• Related Skills
• Documentation in This Repository

Available Resources

📚 references/ - Detailed documentation

• go
• java
• python
• typescript

🔧 scripts/ - Automation scripts

• check docs updated

Quick Start

1. Check Documentation Status

# Via skills CLI
node .scripts/skills-cli.ts doc-sync validate

# Or directly
node -e "import('./.scripts/lib/skills/doc-sync.ts').then(m => m.validateDocs('.'))"

2. Pre-Push Hook Integration

Add documentation validation to your pre-push hook:

# In .git-hooks/pre-push or hooks-checks.js
# Checks if docs need updating when architecture files change

Documentation Validation Checks

Integration with RFC-37

For repositories following RFC-37 documentation standards:

# Install the linter
brew tap bitsoex/homebrew-bitso
brew install bitso-documentation-linter

# Run RFC-37 validation
doclinter --repo-path . --verbose

# Preview Confluence structure
doclinter tree --repo-path .

See the rfc-37-documentation skill for full RFC-37 compliance.

Pre-Push Documentation Check

The system can verify documentation is updated when significant files change:

Architecture Files That Trigger Doc Checks

const ARCHITECTURE_FILES = [
  'technology-hierarchy.json',
  'repo-overrides.json',
  'managed-paths.json',
  '.scripts/convert-rules.ts',
  '.scripts/targeting.ts',
  '.scripts/safe-sync.ts',
  '.scripts/ci-distribute.ts',
  '.github/workflows/ci.yaml'
];

Expected Documentation Updates

When architecture files change, update one of:

• docs/ai-ide-management/concepts/architecture.md
• docs/ai-ide-management/how-tos/targeting-and-inheritance.md
• docs/ai-ide-management/overview.md
• README.md

Skipping the Check

# For a single commit (when docs truly aren't needed)
AI_AGENTS_SKIP_DOCS_CHECK=1 git commit -m "chore: minor config tweak"

# Or document why in commit message
git commit -m "fix: typo in config

No docs update needed - cosmetic change only"

Available Functions

The doc-sync module exports these functions:

import {
  validateDocs,      // Run all documentation checks
  checkReadme,       // Verify README presence
  checkBrokenLinks,  // Find broken internal links
  checkApiDocs,      // Look for API documentation
  checkFreshness,    // Compare doc/code timestamps
  DOC_TOOLS          // Recommended tools by project type
} from './.scripts/lib/skills/doc-sync.ts';

Example Usage

import { validateDocs } from './.scripts/lib/skills/doc-sync.ts';

const result = await validateDocs('.', { quiet: false });

console.log('Passed:', result.passed);
console.log('Issues:', result.issues);
console.log('Warnings:', result.warnings);
console.log('Recommendations:', result.recommendations);

Documentation Tools by Project Type

Best Practices

1. Document As You Code

• Update docs in the same PR as code changes
• Use the pre-push hook to catch missing updates
• Keep README.md as the single source of truth

2. Structure Documentation

Follow RFC-37 structure for consistency:

docs/
├── decisions/          # ADRs (Architecture Decision Records)
├── how-tos/           # Step-by-step guides
├── runbooks/          # Operational procedures
└── {service}/         # Service-specific docs
    ├── concepts/      # Architecture, design
    └── getting-started/

3. Link Related Docs

Use relative links between documentation files. For example, link from one reference file to another using relative paths like ./other-file.md or ../other-folder/file.md.

4. Keep Docs Fresh

• Run freshness checks periodically
• Update docs when APIs change
• Review docs during code reviews

References

Related Skills

Documentation in This Repository

For ai-code-instructions documentation, see docs/ai-ide-management/:

• catalogues/ - Catalogues of rules, commands, MCP, skills
• concepts/ - Architecture and design concepts
• how-tos/ - Step-by-step guides
• mcp/ - MCP configuration docs
• overview.md - Main entry point