Back to Details

blueprints-maintenance

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Maintaining Technical Blueprints

维护技术蓝图

The Sync Problem

同步问题

Documentation drifts from implementation when:
  • Code changes without doc updates
  • New features added without documentation
  • Deprecated features remain documented
  • Behavior changes aren't reflected
当出现以下情况时，文档会与实际实现脱节：
  • 代码变更但未更新文档
  • 添加新功能但未记录文档
  • 已废弃的功能仍保留在文档中
  • 行为变更未在文档中体现

Verification Process

验证流程

Before Making Changes

修改前准备

  1. Find relevant blueprints:
    # Search for blueprints related to your system
Grep("auth", path: "blueprints/", output_mode: "files_with_matches")

# Read the blueprint to understand current documentation
Read("blueprints/authentication.md")
  2. Note what documentation exists:
    • Overview accurate?
    • API documentation complete?
    • Behavior described correctly?
  3. Plan documentation updates alongside code changes
  1. 查找相关蓝图：
    # Search for blueprints related to your system
Grep("auth", path: "blueprints/", output_mode: "files_with_matches")

# Read the blueprint to understand current documentation
Read("blueprints/authentication.md")
  2. 记录现有文档内容：
    • 概述是否准确？
    • API文档是否完整？
    • 行为描述是否正确？
  3. 在规划代码变更的同时规划文档更新

After Making Changes

修改后操作

  1. Re-read the blueprint to verify accuracy:
    Read("blueprints/authentication.md")
  2. Verify each section:
    • Does Overview still describe the purpose?
    • Are all public APIs documented?
    • Is behavior description accurate?
    • Are file paths still correct?
  3. Update the blueprint:
    # Read current content, modify as needed, write back
Write("blueprints/authentication.md", updated_content_with_frontmatter)
  4. Remove stale content - outdated docs mislead
  1. 重新阅读蓝图以验证准确性：
    Read("blueprints/authentication.md")
  2. 验证每个章节：
    • 概述是否仍能描述系统用途？
    • 所有公开API是否都已记录？
    • 行为描述是否准确？
    • 文件路径是否仍然正确？
  3. 更新蓝图：
    # Read current content, modify as needed, write back
Write("blueprints/authentication.md", updated_content_with_frontmatter)
  4. 移除过时内容 - 过时文档会产生误导

Types of Updates

更新类型

Adding New Features

添加新功能

When adding functionality:
  1. Update the Overview if scope expanded
  2. Add new API documentation
  3. Document new behavior
  4. Update Related Systems if new integrations
  5. Add to Files section if new files created
添加功能时：
  1. 如果范围扩大，更新概述部分
  2. 添加新的API文档
  3. 记录新的行为
  4. 如果有新的集成，更新相关系统部分
  5. 如果创建了新文件，添加到文件章节

Modifying Existing Features

修改现有功能

When changing behavior:
  1. Update behavior descriptions
  2. Revise API documentation if signatures changed
  3. Update examples if usage changed
  4. Check related blueprints for impact
变更行为时：
  1. 更新行为描述
  2. 如果签名变更，修订API文档
  3. 如果用法变更，更新示例
  4. 检查相关蓝图是否受影响

Removing Features

移除功能

When deprecating or removing:
  1. Remove API documentation
  2. Remove from behavior section
  3. Update Overview if scope reduced
  4. Consider keeping a "Removed" or "History" note if the change is significant
废弃或移除功能时：
  1. 删除API文档
  2. 从行为章节移除相关内容
  3. 如果范围缩小，更新概述
  4. 如果变更影响重大，可以考虑保留“已移除”或“历史记录”说明

Refactoring

重构

When restructuring without behavior changes:
  1. Update Files section with new paths
  2. Update Architecture if structure changed
  3. Verify examples still work
  4. API documentation usually unchanged
在不改变行为的前提下重构时：
  1. 更新文件章节中的新路径
  2. 如果架构变更，更新架构部分
  3. 验证示例是否仍可正常运行
  4. API文档通常无需变更

Documentation Debt

文档债务

Recognizing Debt

识别债务

Signs blueprints need attention:
  • File paths that don't exist
  • Functions that aren't in the codebase
  • Behavior that doesn't match reality
  • Missing documentation for visible features
蓝图需要维护的迹象：
  • 文件路径不存在
  • 代码库中没有对应的函数
  • 行为与实际不符
  • 可见功能缺少文档

Paying Down Debt

偿还债务

Prioritize by impact:
  1. Critical: Public APIs with wrong docs
  2. High: Core systems undocumented
  3. Medium: Internal systems outdated
  4. Low: Minor inaccuracies
按影响优先级处理：
  1. 关键：公开API文档错误
  2. 高：核心系统未文档化
  3. 中等：内部系统文档过时
  4. 低：轻微不准确

Verification Checklist

验证清单

When reviewing blueprints:
markdown
undefined
审查蓝图时：
markdown
undefined

Verification Checklist

Verification Checklist

  • Overview matches current purpose
  • All public APIs documented
  • API signatures accurate
  • Examples execute correctly
  • Behavior matches implementation
  • File paths exist
  • No removed features documented
  • Related systems links work
  • No duplicate content with other blueprints
undefined
  • Overview matches current purpose
  • All public APIs documented
  • API signatures accurate
  • Examples execute correctly
  • Behavior matches implementation
  • File paths exist
  • No removed features documented
  • Related systems links work
  • No duplicate content with other blueprints
undefined

Keeping Blueprints Fresh

保持蓝图时效性

During Development

开发过程中

  • Treat docs as part of the feature
  • Update blueprint in same commit as code
  • Review blueprint changes in code review
  • 将文档视为功能的一部分
  • 在同一提交中更新蓝图和代码
  • 在代码评审中审查蓝图变更

Regular Maintenance

定期维护

  • Periodically audit blueprints vs code
  • Use 
    /blueprints
    command to regenerate
  • Remove orphaned blueprint files
  • 定期审核蓝图与代码是否一致
  • 使用
    /blueprints
    命令重新生成
  • 移除孤立的蓝图文件

Tooling Support

工具支持

The blueprints hooks automatically:
  • Remind you to check docs (UserPromptSubmit)
  • Verify docs match changes (Stop hook)
蓝图钩子会自动：
  • 提醒你检查文档（UserPromptSubmit）
  • 验证文档是否与变更匹配（Stop hook）

Anti-Patterns

反模式

Don't

不要

  • Leave TODO comments in blueprints indefinitely
  • Copy implementation details that will change
  • Document external libraries (link instead)
  • Keep deprecated feature docs "for reference"
  • 在蓝图中无限期保留TODO注释
  • 复制会变更的实现细节
  • 记录外部库（改用链接）
  • 保留已废弃功能的文档“供参考”

Do

要

  • Delete stale content immediately
  • Update atomically with code
  • Cross-reference rather than duplicate
  • Keep examples minimal but complete
  • 立即删除过时内容
  • 与代码同步原子性更新
  • 使用交叉引用而非重复内容
  • 示例保持精简但完整