sysmem

majiayu000's avatarfrom majiayu000

项目架构链条化初始化和管理技能包，用于自动化项目文档维护、架构分析和代码结构优化。当需要维护项目文档一致性、分析架构风险、检查重复代码或更新模块说明时使用此技能。

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 5, 2026
[Architecture Design]

When & Why to Use This Skill

Sysmem is a comprehensive Claude skill designed for automated project architecture management and documentation maintenance. It streamlines the process of scanning project structures, analyzing architectural risks, and performing intelligent incremental updates to CLAUDE.md and README files. By identifying code duplication and structural inconsistencies, it ensures that project documentation remains a 'ground truth' that accurately reflects the codebase, significantly improving developer productivity and system maintainability.

Use Cases

  • Project Initialization & Baselining: Automatically scan a new or existing repository to generate a standardized project structure and initialize core documentation.
  • Architectural Health Monitoring: Periodically detect duplicate functions, redundant files, and inconsistent API implementations to mitigate technical debt.
  • Intelligent Documentation Sync: Perform incremental updates to module READMEs and CLAUDE.md based on actual code changes, preserving manual developer notes while ensuring structural accuracy.
  • Refactoring Risk Assessment: Analyze the impact of structural changes and identify cleanup opportunities before major code migrations or optimizations.
  • Cross-Environment Context Management: Synchronize project metadata and architectural state between Claude Code and Codex environments to maintain a consistent agent workspace.
namesysmem
description项目架构链条化初始化和管理技能包，用于自动化项目文档维护、架构分析和代码结构优化。当需要维护项目文档一致性、分析架构风险、检查重复代码或更新模块说明时使用此技能。

Sysmem

Overview

Sysmem提供项目架构链条化管理，通过自动化扫描、文档更新、架构分析和清理建议，确保项目文档结构的一致性和完整性。支持自动化项目初始化、模块化管理和持续架构健康监控。

Core Capabilities

1. 项目扫描和结构分析

使用scripts/scan_project.py扫描整个项目结构：

  • 自动发现所有模块目录和readme文件
  • 提取模块功能摘要和文件组织结构
  • 生成标准化的项目结构JSON文件
  • 识别未在readme中记录的新文件

使用场景：

  • 项目初始化时建立基线结构
  • 定期检查项目结构变化
  • 为其他功能提供数据基础

执行命令：

python3 /path/to/skill/scripts/scan_project.py /path/to/project

重要: 所有脚本都会在目标项目的 .claude/skill/sysmem/ 目录中生成数据文件，不会污染项目根目录或skill目录。

2. 智能数据收集和文档更新

使用数据收集 + Claude智能处理的组合方式：

第一步：数据收集

python3 /path/to/skill/scripts/collect_data.py /path/to/project

收集器负责：

  • 扫描项目结构，提取模块信息
  • 分析现有文档，识别变化
  • 检测架构问题和重复代码
  • 生成结构化的分析数据

第二步：Claude智能更新 将收集到的数据交给Claude处理：

  • 基于现有CLAUDE.md内容进行增量更新，而非覆盖
  • 保持用户自定义的内容和格式
  • 智能判断更新内容，避免误修改
  • 利用Claude的理解能力优化文档结构

正确使用方式：

  1. 运行数据收集脚本：python3 scripts/collect_data.py
  2. 将生成的project_data.json内容提供给Claude
  3. 要求Claude基于数据进行智能更新：基于project_data.json，请更新我的CLAUDE.md和各模块README，保持现有内容不变，只更新需要变化的部分

优势：

  • ✅ 保护用户自定义内容
  • ✅ 智能增量更新，避免覆盖
  • ✅ 利用Claude的理解能力
  • ✅ 保持文档格式和风格一致

3. 架构风险分析和重复代码检测

使用scripts/analyze_architecture.py进行深度分析：

  • 检测文件重复（同名文件、相似内容）
  • 分析函数重复（Python代码的函数签名和逻辑相似度）
  • 识别实现不一致（配置文件结构、API接口格式）
  • 评估架构复杂度和文档完整性
  • 生成详细的分析报告和改进建议

使用场景：

  • 代码重构前的风险评估
  • 定期架构健康检查
  • 新模块加入的一致性验证
  • 技术债务评估和优化规划

分析标准：参考references/analysis_criteria.md中的详细规则

4. 文件清理建议

基于项目扫描结果提供清理建议：

  • 列出未在readme中记录的文件
  • 标识可能是临时文件或废弃代码
  • 提供模块级别的清理建议
  • 支持用户决策和批量清理操作

使用场景：

  • 项目整理和优化
  • 移除不再需要的代码文件
  • 保持项目结构清洁

5. 模块readme结构化管理

基于references/readme_template.md维护标准化文档：

  • 第一行必须包含结构化功能描述
  • 标准化的文件功能说明格式
  • 重要定义的Ground Truth标记
  • 代码变更历史记录

使用场景：

  • 新模块创建时的文档初始化
  • 现有模块文档的标准化改造
  • 维护文档格式一致性

6. 双重环境支持和同步

新增的双重环境管理功能：

  • Claude Code集成：在Claude环境中进行数据收集和初步分析
  • Codex集成：在Codex环境中进行深度分析和代理协作
  • 跨环境同步：自动同步数据文件和文档变更
  • 统一管理：提供统一的配置和工具接口

双重环境工作流程：

# Claude Code环境（主环境）
python3 /path/to/skill/scripts/collect_data.py /path/to/project

# 同步到Codex环境
python3 scripts/sync-env.sh --to-codex

# Codex环境中使用代理
from agents.sync_agent import SyncAgent
agent = SyncAgent()
agent.sync_with_claude("/path/to/project")

同步机制：

  • 数据文件自动同步：.claude/skill/sysmem/ ↔ .codex/sysmem/
  • 文档一致性检查：CLAUDE.md ↔ AGENTS.md
  • 配置文件统一：双重环境共享配置
  • 冲突解决策略：Claude Code优先级

Workflow Decision Tree

首次使用Sysmem

用户请求: "初始化sysmem来管理我的项目架构"
↓
1. 执行数据收集: python3 scripts/collect_data.py
2. Claude分析收集到的project_data.json
3. 检查现有CLAUDE.md和readme文件状态
4. Claude基于数据进行智能文档更新（增量更新，不覆盖）
5. 提供架构分析和改进建议

定期维护流程

用户请求: "用sysmem更新项目文档"
↓
1. 执行数据收集: python3 scripts/collect_data.py
2. 将project_data.json提供给Claude
3. Claude对比分析，识别变化和需要更新的部分
4. 进行智能增量更新，保护用户自定义内容
5. 生成更新报告和建议

架构分析流程

用户请求: "分析payment模块的架构风险"
↓
1. 执行数据收集: python3 scripts/collect_data.py
2. Claude分析project_data.json中的架构问题
3. 检查重复代码、配置不一致等问题
4. 提供详细的风险评估和解决建议
5. 用户根据建议进行代码优化

Resources

scripts/

collect_data.py - 智能数据收集器，收集项目结构、文档状态和架构问题 scan_project.py - 基础项目扫描器，遍历项目结构并收集文件信息 analyze_architecture.py - 架构分析器，检测风险和重复代码

注意: 推荐使用 collect_data.py + Claude智能处理的组合方式，避免直接修改文件。

references/

readme_template.md - 标准readme模板，确保文档格式一致性 claude_md_template.md - CLAUDE.md结构模板和示例 analysis_criteria.md - 架构分析标准和规则定义

assets/

project_structure_example.json - 项目结构数据格式示例