Back to Details

module-based-refactor

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Module-Based Refactor Skill

基于模块的重构技能

Reorganize a repository from flat structure to a consistent module-based 5-layer architecture while preserving git history. Includes comprehensive cleanup of artifacts, runtime data, and hidden folders.
将仓库从扁平结构重组为统一的基于模块的5层架构，同时保留Git历史记录。包括对工件、运行时数据和隐藏文件夹的全面清理。

Version Metadata

版本元数据

yaml
version: 3.2.0
python_min_version: '3.10'
dependencies: []
compatibility:
  tested_python:
  - '3.10'
  - '3.11'
  - '3.12'
  - '3.13'
  os:
  - Windows
  - Linux
  - macOS
yaml
version: 3.2.0
python_min_version: '3.10'
dependencies: []
compatibility:
  tested_python:
  - '3.10'
  - '3.11'
  - '3.12'
  - '3.13'
  os:
  - Windows
  - Linux
  - macOS

When to Use

适用场景

  • Reorganizing a flat repository structure to module-based layout
  • Consolidating scattered modules into a unified hierarchy
  • Standardizing project structure across multiple layers (src, tests, specs, docs, examples)
  • Migrating import paths while preserving git history
  • Creating a scalable architecture for growing codebases
  • Cleaning up root-level artifacts (log files, temp files, build artifacts)
  • Consolidating duplicate directories (agents/, coordination/, memory/)
  • Reviewing and removing obsolete hidden folders
  • Relocating test outputs and prototype code
  • 将扁平仓库结构重组为基于模块的布局
  • 将分散的模块整合到统一的层级结构中
  • 跨多个层（src、tests、specs、docs、examples）标准化项目结构
  • 在保留Git历史记录的同时迁移导入路径
  • 为不断增长的代码库创建可扩展的架构
  • 清理根级工件（日志文件、临时文件、构建工件）
  • 合并重复目录（agents/、coordination/、memory/）
  • 检查并移除过时的隐藏文件夹
  • 迁移测试输出和原型代码

Pre-flight Checks

预检查

CRITICAL: Run these checks before starting any reorganization.
至关重要：在开始任何重组之前运行这些检查。

1. Git Tracking Status

1. Git跟踪状态

bash
undefined
bash
undefined

Check what is tracked vs untracked

检查已跟踪和未跟踪的文件

git ls-files | head -50 git ls-files --others --exclude-standard | head -50
git ls-files | head -50 git ls-files --others --exclude-standard | head -50

List all untracked files at root level

列出根目录下所有未跟踪文件

git ls-files --others --exclude-standard | grep -v "/"
git ls-files --others --exclude-standard | grep -v "/"

Check for ignored files that might need cleanup

检查可能需要清理的被忽略文件

git status --ignored
undefined
git status --ignored
undefined

2. Duplicate Directory Detection

2. 重复目录检测

bash
undefined
bash
undefined

Find duplicate agent directories

查找重复的agent目录

ls -la agents/ .claude/agents/ .claude/agent-library/ 2>/dev/null
ls -la agents/ .claude/agents/ .claude/agent-library/ 2>/dev/null

Find duplicate coordination/memory directories

查找重复的coordination/memory目录

Find duplicate skill locations

查找重复的skill位置

find . -type d -name "skills" 2>/dev/null
undefined
find . -type d -name "skills" 2>/dev/null
undefined

3. Identify Runtime vs Config Files

3. 识别运行时文件与配置文件

bash
undefined
bash
undefined

Runtime data (should NOT be in git)

运行时数据（不应在Git中）

find . -name ".log" -o -name ".tmp" -o -name "pycache" 2>/dev/null
find . -name ".log" -o -name ".tmp" -o -name "pycache" 2>/dev/null

Config files (SHOULD be in git)

配置文件（应在Git中）

find . -name ".json" -o -name ".yaml" -o -name "*.toml" 2>/dev/null | head -30
find . -name ".json" -o -name ".yaml" -o -name "*.toml" 2>/dev/null | head -30

Large files that might be test data

可能是测试数据的大文件

find . -size +1M -type f 2>/dev/null
undefined
find . -size +1M -type f 2>/dev/null
undefined

4. Hidden Folder Inventory

4. 隐藏文件夹清单

bash
undefined
bash
undefined

List all hidden folders at root

列出根目录下所有隐藏文件夹

ls -la .* 2>/dev/null | grep "^d"
ls -la .* 2>/dev/null | grep "^d"

Common hidden folders to review:

需要检查的常见隐藏文件夹：

.agent-os/ - May contain duplicate agent configs

.agent-os/ - 可能包含重复的agent配置

.ai/ - Legacy AI coordination

.ai/ - 遗留AI协调目录

.drcode/ - DR Code artifacts

.drcode/ - DR Code工件

.claude/ - Claude configuration (KEEP)

.claude/ - Claude配置（保留）

.git/ - Git data (KEEP)

.git/ - Git数据（保留）

.venv/ - Virtual environment (should be ignored)

.venv/ - 虚拟环境（应被忽略）

undefined
undefined

5. Identify Stale Artifacts

5. 识别陈旧工件

bash
undefined
bash
undefined

Find log files in root

查找根目录下的日志文件

ls *.log 2>/dev/null
ls *.log 2>/dev/null

Find test output files

查找测试输出文件

ls _output. test_*.txt *.html 2>/dev/null
ls _output. test_*.txt *.html 2>/dev/null

Find build artifacts

查找构建工件

ls *.egg-info dist/ build/ 2>/dev/null
undefined
ls *.egg-info dist/ build/ 2>/dev/null
undefined

Pre-consolidation Analysis

合并前分析

Before merging hidden folders, perform a thorough analysis to understand scope and identify conflicts.
在合并隐藏文件夹之前，执行全面分析以了解范围并识别冲突。

1. Count Tracked Files per Hidden Folder

1. 统计每个隐藏文件夹中的已跟踪文件数

bash
undefined
bash
undefined

Count tracked files in each hidden folder

统计每个隐藏文件夹中的已跟踪文件数

git ls-files .claude/ | wc -l git ls-files .agent-os/ | wc -l git ls-files .ai/ | wc -l
git ls-files .claude/ | wc -l git ls-files .agent-os/ | wc -l git ls-files .ai/ | wc -l

Example output:

示例输出：

.claude/: 519 files

.claude/: 519个文件

.agent-os/: 129 files

.agent-os/: 129个文件

.ai/: 52 files

.ai/: 52个文件

Total after merge: 519 + 129 + 52 = 700 files (minus overlaps)

合并后总数：519 + 129 + 52 = 700个文件（减去重叠部分）

undefined
undefined

2. Identify Overlapping Content

2. 识别重叠内容

bash
undefined
bash
undefined

Compare directory structures

比较目录结构

ls -la .claude/ .agent-os/ .ai/ 2>/dev/null
ls -la .claude/ .agent-os/ .ai/ 2>/dev/null

Find common subdirectory names

查找公共子目录名称

comm -12 <(ls .claude/ | sort) <(ls .agent-os/ | sort) comm -12 <(ls .claude/ | sort) <(ls .ai/ | sort)
comm -12 <(ls .claude/ | sort) <(ls .agent-os/ | sort) comm -12 <(ls .claude/ | sort) <(ls .ai/ | sort)

Common overlap patterns:

常见重叠模式：

- commands/ in both .claude/ and .agent-os/

- .claude/和.agent-os/中都有commands/

- hooks/ in both .claude/ and .agent-os/

- .claude/和.agent-os/中都有hooks/

- docs/ in multiple locations

- 多个位置都有docs/

undefined
undefined

3. Determine Authoritative Source

3. 确定权威来源

bash
undefined
bash
undefined

Check which folder has more recent commits

检查哪个文件夹的提交更新更近期

git log --oneline -5 -- .claude/ git log --oneline -5 -- .agent-os/ git log --oneline -5 -- .ai/
git log --oneline -5 -- .claude/ git log --oneline -5 -- .agent-os/ git log --oneline -5 -- .ai/

Check file modification dates

检查文件修改日期

find .claude/ -type f -printf '%T+ %p\n' | sort -r | head -10 find .agent-os/ -type f -printf '%T+ %p\n' | sort -r | head -10
find .claude/ -type f -printf '%T+ %p
' | sort -r | head -10 find .agent-os/ -type f -printf '%T+ %p
' | sort -r | head -10

Check for unique content in each folder

检查每个文件夹中的唯一内容

diff -rq .claude/docs/ .agent-os/docs/ 2>/dev/null | head -20
undefined
diff -rq .claude/docs/ .agent-os/docs/ 2>/dev/null | head -20
undefined

4. Create Merge Plan

4. 创建合并计划

Based on analysis, plan the merge strategy:
Source FolderDestinationStrategyReason
.agent-os/commands/.claude/commands/legacy-scripts/Rename to avoid conflict.claude/commands/ already exists
.agent-os/hooks/.claude/hooks/legacy/Rename to avoid conflict.claude/hooks/ already exists
.agent-os/docs/.claude/docs/MergeUnique documentation content
.agent-os/standards/.claude/standards/Copy (new)Does not exist in .claude/
.ai/implementation-history/.claude/implementation-history/Copy (new)Unique content
Conflicting README.mdREADME-legacy.mdRenamePreserve both versions
基于分析结果，制定合并策略：
源文件夹目标位置策略原因
.agent-os/commands/.claude/commands/legacy-scripts/重命名以避免冲突.claude/commands/已存在
.agent-os/hooks/.claude/hooks/legacy/重命名以避免冲突.claude/hooks/已存在
.agent-os/docs/.claude/docs/合并唯一的文档内容
.agent-os/standards/.claude/standards/复制（新增）.claude/中不存在该目录
.ai/implementation-history/.claude/implementation-history/复制（新增）唯一内容
冲突的README.mdREADME-legacy.md重命名保留两个版本

Parallel Execution Strategy

并行执行策略

Agent Spawn Patterns

Agent生成模式

Use parallel subagents for faster reorganization. Tasks that don't have dependencies can run simultaneously.
使用并行子代理加快重组速度。无依赖的任务可以同时运行。

Phase 1: Analysis (PARALLEL)

阶段1：分析（并行）

javascript
// All analysis tasks can run in parallel
Task("Analyze source structure", "List all directories in src/ and identify modules vs infrastructure", "explorer")
Task("Analyze test structure", "List all directories in tests/ and identify test modules", "explorer")
Task("Analyze specs/docs", "List all directories in specs/ and docs/", "explorer")
Task("Inventory root artifacts", "List all files at root level, identify logs/temp/build artifacts", "explorer")
Task("Hidden folder audit", "List all hidden folders, check git tracking status", "explorer")
javascript
// 所有分析任务可并行运行
Task("Analyze source structure", "List all directories in src/ and identify modules vs infrastructure", "explorer")
Task("Analyze test structure", "List all directories in tests/ and identify test modules", "explorer")
Task("Analyze specs/docs", "List all directories in specs/ and docs/", "explorer")
Task("Inventory root artifacts", "List all files at root level, identify logs/temp/build artifacts", "explorer")
Task("Hidden folder audit", "List all hidden folders, check git tracking status", "explorer")

Phase 2: Directory Creation (SEQUENTIAL)

阶段2：目录创建（串行）

bash
undefined
bash
undefined

Must be sequential - directories must exist before moves

必须串行执行 - 移动文件前目录必须存在

mkdir -p src/<package>/modules mkdir -p tests/modules mkdir -p specs/modules mkdir -p docs/modules mkdir -p examples/modules
undefined
mkdir -p src/<package>/modules mkdir -p tests/modules mkdir -p specs/modules mkdir -p docs/modules mkdir -p examples/modules
undefined

Phase 3: Module Moves (PARALLEL by module)

阶段3：模块移动（按模块并行）

javascript
// Each module can be moved in parallel (no cross-dependencies)
Task("Move aqwa module", "git mv all aqwa files across 5 layers", "coder")
Task("Move catenary module", "git mv all catenary files across 5 layers", "coder")
Task("Move orcaflex module", "git mv all orcaflex files across 5 layers", "coder")
Task("Move mooring module", "git mv all mooring files across 5 layers", "coder")
javascript
undefined

Phase 3.5: Hidden Folder Consolidation (PARALLEL by folder)

每个模块可并行移动（无跨依赖）

javascript
// Each hidden folder can be consolidated in parallel (no cross-dependencies)
Task("Consolidate .agent-os", "Merge .agent-os/ into .claude/ with conflict resolution", "Bash")
Task("Consolidate .ai", "Merge .ai/ into .claude/ preserving unique content", "Bash")
Task("Consolidate .drcode", "Review and merge .drcode/ artifacts if valuable", "Bash")
Consolidation Commands Pattern:
bash
undefined
Task("Move aqwa module", "git mv all aqwa files across 5 layers", "coder") Task("Move catenary module", "git mv all catenary files across 5 layers", "coder") Task("Move orcaflex module", "git mv all orcaflex files across 5 layers", "coder") Task("Move mooring module", "git mv all mooring files across 5 layers", "coder")
undefined

Phase 3.5a: Consolidate .agent-os/ (129 files)

阶段3.5：隐藏文件夹整合（按文件夹并行）

Move conflicting directories with rename

—
git mv .agent-os/commands .claude/commands/legacy-scripts git mv .agent-os/hooks .claude/hooks/legacy
javascript
undefined

Move non-conflicting directories directly

每个隐藏文件夹可并行整合（无跨依赖）

git mv .agent-os/standards .claude/standards git mv .agent-os/docs/* .claude/docs/
Task("Consolidate .agent-os", "Merge .agent-os/ into .claude/ with conflict resolution", "Bash") Task("Consolidate .ai", "Merge .ai/ into .claude/ preserving unique content", "Bash") Task("Consolidate .drcode", "Review and merge .drcode/ artifacts if valuable", "Bash")

**整合命令模式：**

```bash

Handle conflicting README

阶段3.5a：整合.agent-os/（129个文件）

—

重命名移动冲突目录

git mv .agent-os/README.md .claude/README-agent-os-legacy.md
git mv .agent-os/commands .claude/commands/legacy-scripts git mv .agent-os/hooks .claude/hooks/legacy

Phase 3.5b: Consolidate .ai/ (52 files)

直接移动无冲突目录

Move unique content

—
git mv .ai/implementation-history .claude/implementation-history git mv .ai/docs/* .claude/docs/
git mv .agent-os/standards .claude/standards git mv .agent-os/docs/* .claude/docs/

Handle conflicting README

处理冲突的README

git mv .ai/README.md .claude/README-ai-legacy.md
git mv .agent-os/README.md .claude/README-agent-os-legacy.md

Phase 3.5c: Remove empty source folders

阶段3.5b：整合.ai/（52个文件）

—

移动唯一内容

rm -rf .agent-os/ .ai/
undefined
git mv .ai/implementation-history .claude/implementation-history git mv .ai/docs/* .claude/docs/

Phase 4: Import Updates (PARALLEL by file type)

处理冲突的README

javascript
// Import updates can be parallelized by file type
Task("Update source imports", "Update imports in src/**/*.py", "coder")
Task("Update test imports", "Update imports in tests/**/*.py", "coder")
Task("Update example imports", "Update imports in examples/**/*.py", "coder")
git mv .ai/README.md .claude/README-ai-legacy.md

Phase 5: Cleanup (PARALLEL)

阶段3.5c：移除空源文件夹

javascript
// Cleanup tasks are independent
Task("Remove root artifacts", "Delete log files, temp files from root", "coder")
Task("Consolidate agent dirs", "Move agents/ content to .claude/agent-library/", "coder")
Task("Clean hidden folders", "Remove obsolete .agent-os/, .ai/, .drcode/", "coder")
Task("Update .gitignore", "Add runtime data patterns to .gitignore", "coder")
rm -rf .agent-os/ .ai/
undefined

Phase 6: Verification (PARALLEL then SEQUENTIAL)

阶段4：导入路径更新（按文件类型并行）

javascript
// Parallel verification
Task("Verify imports", "Test all import statements work", "tester")
Task("Verify git status", "Check git status is clean, no broken files", "tester")
Task("Run test suite", "Run pytest to verify nothing broken", "tester")

// Sequential final review
Task("Final structure review", "Compare actual structure to target structure", "reviewer")
javascript
undefined

Parallel vs Sequential Decision Matrix

导入路径更新可按文件类型并行执行

Task TypeParallel?Reason
Analysis/InventoryYESRead-only, no conflicts
Directory creationNOOrder matters for parent dirs
Module moves (same module)NOFiles may reference each other
Module moves (different modules)YESIndependent file sets
Hidden folder consolidationYESEach folder merged independently
Import updates (same file)NOWould cause conflicts
Import updates (different files)YESNo file conflicts
Cleanup tasksYESIndependent operations
Test executionNOMay have shared fixtures
VerificationMIXEDSome parallel, final review sequential
Task("Update source imports", "Update imports in src//*.py", "coder") Task("Update test imports", "Update imports in tests//.py", "coder") Task("Update example imports", "Update imports in examples/**/.py", "coder")
undefined

Target Structure

阶段5：清理（并行）

The 5-layer module architecture:
src/<package>/modules/<module_name>/
tests/modules/<module_name>/
specs/modules/<module_name>/
docs/modules/<module_name>/
examples/modules/<module_name>/
javascript
undefined

Example: digitalmodel Package

清理任务相互独立

src/digitalmodel/modules/
├── __init__.py
├── aqwa/
│   ├── __init__.py
│   ├── aqwa_reader.py
│   └── aqwa_utilities.py
├── catenary/
│   ├── __init__.py
│   ├── catenary.py
│   └── catenary_riser.py
├── fea_model/
│   ├── __init__.py
│   └── line_components.py
├── mooring/
│   ├── __init__.py
│   └── mooring.py
├── orcaflex/
│   ├── __init__.py
│   └── OrcaFlexAnalysis.py
└── pipe_capacity/
    ├── __init__.py
    └── custom/

tests/modules/
├── conftest.py
├── aqwa/
│   └── test_aqwa_reader.py
├── catenary/
│   └── test_catenary.py
└── orcaflex/
    └── test_orcaflex_analysis.py

specs/modules/
├── .gitkeep
├── aqwa/
│   └── spec.md
└── orcaflex/
    └── spec.md

docs/modules/
├── aqwa/
│   └── README.md
└── orcaflex/
    └── README.md

examples/modules/
├── aqwa/
│   └── basic_analysis.py
└── orcaflex/
    └── batch_processing.py
Task("Remove root artifacts", "Delete log files, temp files from root", "coder") Task("Consolidate agent dirs", "Move agents/ content to .claude/agent-library/", "coder") Task("Clean hidden folders", "Remove obsolete .agent-os/, .ai/, .drcode/", "coder") Task("Update .gitignore", "Add runtime data patterns to .gitignore", "coder")
undefined

Process

阶段6：验证（先并行后串行）

Phase 1: Analysis

—
  1. List all top-level directories
    bash
    ls -la src/<package>/
ls -la tests/
ls -la specs/
  2. Identify modules vs infrastructure
    • Modules: Domain-specific code directories (e.g., 
      aqwa/
      , 
      catenary/
      , 
      orcaflex/
      )
    • Infrastructure: Support directories that should stay at root level
  3. Document current state
    bash
    # List all Python files to understand module scope
find src/<package> -name "*.py" -type f | head -50

# Check for existing module imports
grep -r "from <package>" --include="*.py" . | head -20
javascript
undefined

Phase 2: Planning

并行验证

  1. Create migration plan
    • List all modules to be moved
    • Identify dependencies between modules
    • Plan import path changes
  2. Identify infrastructure folders (keep at root)
    # Tests infrastructure
tests/test_data/
tests/test_configs/
tests/fixtures/
tests/conftest.py (root level)

# Specs infrastructure
specs/templates/
specs/features/

# Project infrastructure
config/
scripts/
.claude/
Task("Verify imports", "Test all import statements work", "tester") Task("Verify git status", "Check git status is clean, no broken files", "tester") Task("Run test suite", "Run pytest to verify nothing broken", "tester")

Phase 3: Create Target Directories

串行最终检查

bash
undefined
Task("Final structure review", "Compare actual structure to target structure", "reviewer")
undefined

Create module directories with git-tracked placeholders

并行与串行决策矩阵

mkdir -p src/<package>/modules mkdir -p tests/modules mkdir -p specs/modules mkdir -p docs/modules mkdir -p examples/modules
任务类型是否并行？原因
分析/清单是只读操作，无冲突
目录创建否父目录创建顺序很重要
模块移动（同一模块）否文件可能相互引用
模块移动（不同模块）是文件集相互独立
隐藏文件夹整合是每个文件夹独立合并
导入更新（同一文件）否会导致冲突
导入更新（不同文件）是无文件冲突
清理任务是操作相互独立
测试执行否可能有共享夹具
验证混合部分并行，最终检查串行

Add .gitkeep for empty directories

目标结构

touch specs/modules/.gitkeep touch docs/modules/.gitkeep touch examples/modules/.gitkeep
undefined
5层模块架构：
src/<package>/modules/<module_name>/
tests/modules/<module_name>/
specs/modules/<module_name>/
docs/modules/<module_name>/
examples/modules/<module_name>/

Phase 4: Move with Git History Preservation

示例：digitalmodel包

CRITICAL: Always use 
git mv
to preserve history.
bash
undefined
src/digitalmodel/modules/
├── __init__.py
├── aqwa/
│   ├── __init__.py
│   ├── aqwa_reader.py
│   └── aqwa_utilities.py
├── catenary/
│   ├── __init__.py
│   ├── catenary.py
│   └── catenary_riser.py
├── fea_model/
│   ├── __init__.py
│   └── line_components.py
├── mooring/
│   ├── __init__.py
│   └── mooring.py
├── orcaflex/
│   ├── __init__.py
│   └── OrcaFlexAnalysis.py
└── pipe_capacity/
    ├── __init__.py
    └── custom/

tests/modules/
├── conftest.py
├── aqwa/
│   └── test_aqwa_reader.py
├── catenary/
│   └── test_catenary.py
└── orcaflex/
    └── test_orcaflex_analysis.py

specs/modules/
├── .gitkeep
├── aqwa/
│   └── spec.md
└── orcaflex/
    └── spec.md

docs/modules/
├── aqwa/
│   └── README.md
└── orcaflex/
    └── README.md

examples/modules/
├── aqwa/
│   └── basic_analysis.py
└── orcaflex/
    └── batch_processing.py

Move source modules

流程

—

阶段1：分析

git mv src/<package>/<module> src/<package>/modules/<module>
  1. 列出所有顶层目录
    bash
    ls -la src/<package>/
ls -la tests/
ls -la specs/
  2. 识别模块与基础设施
    • 模块：特定领域的代码目录（如
      aqwa/
      、
      catenary/
      、
      orcaflex/
      ）
    • 基础设施：应保留在根级别的支持目录
  3. 记录当前状态
    bash
    # 列出所有Python文件以了解模块范围
find src/<package> -name "*.py" -type f | head -50

# 检查现有模块导入
grep -r "from <package>" --include="*.py" . | head -20

Move test modules

阶段2：规划

git mv tests/<module> tests/modules/<module>
  1. 创建迁移计划
    • 列出所有要移动的模块
    • 识别模块之间的依赖关系
    • 规划导入路径变更
  2. 识别基础设施文件夹（保留在根级别）
    # 测试基础设施
tests/test_data/
tests/test_configs/
tests/fixtures/
tests/conftest.py（根级别）

# 规格文档基础设施
specs/templates/
specs/features/

# 项目基础设施
config/
scripts/
.claude/

Move spec modules

阶段3：创建目标目录

git mv specs/<module> specs/modules/<module>
bash
undefined

Move doc modules

创建带Git跟踪占位符的模块目录

git mv docs/<module> docs/modules/<module>
mkdir -p src/<package>/modules mkdir -p tests/modules mkdir -p specs/modules mkdir -p docs/modules mkdir -p examples/modules

Move example modules

为空目录添加.gitkeep

git mv examples/<module> examples/modules/<module>
undefined
touch specs/modules/.gitkeep touch docs/modules/.gitkeep touch examples/modules/.gitkeep
undefined

Example: Moving aqwa module

阶段4：保留Git历史的移动操作

bash
undefined
至关重要：始终使用
git mv
来保留历史记录。
bash
undefined

Source

移动源模块

git mv src/digitalmodel/aqwa src/digitalmodel/modules/aqwa
git mv src/<package>/<module> src/<package>/modules/<module>

Tests

移动测试模块

git mv tests/aqwa tests/modules/aqwa
git mv tests/<module> tests/modules/<module>

Specs (if exists)

移动规格模块

git mv specs/aqwa specs/modules/aqwa
git mv specs/<module> specs/modules/<module>

Docs (if exists)

移动文档模块

git mv docs/aqwa docs/modules/aqwa
undefined
git mv docs/<module> docs/modules/<module>

Phase 5: Update Imports

移动示例模块

  1. Search for old import patterns
    bash
    # Find all files with old import paths
grep -r "from <package>.<module>" --include="*.py" .
grep -r "import <package>.<module>" --include="*.py" .
  2. Update import statements
    bash
    # Update imports (example using sed)
find . -name "*.py" -exec sed -i 's/from digitalmodel.aqwa/from digitalmodel.modules.aqwa/g' {} \;
find . -name "*.py" -exec sed -i 's/import digitalmodel.aqwa/import digitalmodel.modules.aqwa/g' {} \;
  3. Common import transformations
    python
    # Before
from digitalmodel.aqwa import aqwa_reader
from digitalmodel.catenary.catenary import Catenary

# After
from digitalmodel.modules.aqwa import aqwa_reader
from digitalmodel.modules.catenary.catenary import Catenary
git mv examples/<module> examples/modules/<module>
undefined

Phase 6: Create init.py Files

示例：移动aqwa模块

  1. Module root init.py
    python
    # src/<package>/modules/__init__.py
"""
Module-based architecture for <package>.

Available modules:
- aqwa: AQWA hydrodynamic analysis
- catenary: Catenary riser analysis
- fea_model: FEA model components
- mooring: Mooring system analysis
- orcaflex: OrcaFlex simulation
- pipe_capacity: Pipe capacity calculations
"""

from digitalmodel.modules import aqwa
from digitalmodel.modules import catenary
from digitalmodel.modules import fea_model
from digitalmodel.modules import mooring
from digitalmodel.modules import orcaflex
from digitalmodel.modules import pipe_capacity

__all__ = [
    "aqwa",
    "catenary",
    "fea_model",
    "mooring",
    "orcaflex",
    "pipe_capacity",
]
  2. Individual module init.py
    python
    # src/<package>/modules/<module>/__init__.py
"""
<Module Name> - Brief description.

Key classes and functions exported from this module.
"""

from digitalmodel.modules.<module>.<main_file> import MainClass
from digitalmodel.modules.<module>.<utils_file> import utility_function

__all__ = ["MainClass", "utility_function"]
bash
undefined

Phase 7: Verification

源文件

  1. Test imports work
    python
    # test_imports.py
import sys
sys.path.insert(0, 'src')

# Test new import paths
from digitalmodel.modules.aqwa import aqwa_reader
from digitalmodel.modules.catenary.catenary import Catenary
from digitalmodel.modules.orcaflex import OrcaFlexAnalysis

print("All imports successful!")
  2. Run test suite
    bash
    uv run pytest tests/ -v
  3. Check for broken imports
    bash
    # Find any remaining old import patterns
grep -r "from digitalmodel\." --include="*.py" . | grep -v "modules"
git mv src/digitalmodel/aqwa src/digitalmodel/modules/aqwa

Checklist

测试文件

Pre-Refactor

—
  • Git working directory is clean
  • All tests pass before refactor
  • Created backup branch
  • Documented current structure
  • Pre-flight checks completed (see Pre-flight Checks section)
  • Duplicate directories identified
  • Runtime vs config files categorized
  • Hidden folders inventoried
git mv tests/aqwa tests/modules/aqwa

During Refactor

规格文件（如果存在）

Module Structure

—
  • All modules moved to modules/ subdirectory using 
    git mv
  • tests/modules/ created and populated
  • specs/modules/ created (with .gitkeep if empty)
  • docs/modules/ created (with .gitkeep if empty)
  • examples/modules/ created (with .gitkeep if empty)
git mv specs/aqwa specs/modules/aqwa

Root-Level Artifact Cleanup

文档（如果存在）

  • Log files removed (*.log)
  • Temp files removed (*.tmp, *.temp)
  • Build artifacts removed (dist/, build/, *.egg-info/)
  • Cache files removed (pycache/, .pytest_cache/)
  • Test output files relocated or removed
  • Prototype/experimental code relocated to examples/ or removed
git mv docs/aqwa docs/modules/aqwa
undefined

Directory Consolidation

阶段5：更新导入路径

  • agents/ content moved to .claude/agent-library/
  • Duplicate skill directories merged
  • Empty directories removed
  1. 搜索旧导入模式
    bash
    # 查找所有包含旧导入路径的文件
grep -r "from <package>.<module>" --include="*.py" .
grep -r "import <package>.<module>" --include="*.py" .
  2. 更新导入语句
    bash
    # 更新导入（使用sed的示例）
find . -name "*.py" -exec sed -i 's/from digitalmodel.aqwa/from digitalmodel.modules.aqwa/g' {} \\;
find . -name "*.py" -exec sed -i 's/import digitalmodel.aqwa/import digitalmodel.modules.aqwa/g' {} \\;
  3. 常见导入转换
    python
    # 转换前
from digitalmodel.aqwa import aqwa_reader
from digitalmodel.catenary.catenary import Catenary

# 转换后
from digitalmodel.modules.aqwa import aqwa_reader
from digitalmodel.modules.catenary.catenary import Catenary

Hidden Folder Review

阶段6：创建__init__.py文件

  • .agent-os/ - reviewed and cleaned (usually remove)
  • .ai/ - reviewed and cleaned (usually remove)
  • .drcode/ - reviewed and cleaned (usually remove)
  • .claude/ - kept and organized
  • .venv/ - confirmed in .gitignore
  1. 模块根目录__init__.py
    python
    # src/<package>/modules/__init__.py
"""
<package>的基于模块的架构。

可用模块：
- aqwa: AQWA水动力分析
- catenary: 悬链线立管分析
- fea_model: FEA模型组件
- mooring: 系泊系统分析
- orcaflex: OrcaFlex仿真
- pipe_capacity: 管道容量计算
"""

from digitalmodel.modules import aqwa
from digitalmodel.modules import catenary
from digitalmodel.modules import fea_model
from digitalmodel.modules import mooring
from digitalmodel.modules import orcaflex
from digitalmodel.modules import pipe_capacity

__all__ = [
    "aqwa",
    "catenary",
    "fea_model",
    "mooring",
    "orcaflex",
    "pipe_capacity",
]
  2. 单个模块的__init__.py
    python
    # src/<package>/modules/<module>/__init__.py
"""
<Module Name> - 简要描述。

此模块导出的关键类和函数。
"""

from digitalmodel.modules.<module>.<main_file> import MainClass
from digitalmodel.modules.<module>.<utils_file> import utility_function

__all__ = ["MainClass", "utility_function"]

Test Output Relocation

阶段7：验证

  • HTML reports moved to tests/reports/ or removed
  • Coverage reports moved to tests/coverage/ or removed
  • Screenshot outputs moved to tests/snapshots/ or removed
  • Benchmark results moved to tests/benchmarks/ or removed
  1. 测试导入是否正常工作
    python
    # test_imports.py
import sys
sys.path.insert(0, 'src')

# 测试新导入路径
from digitalmodel.modules.aqwa import aqwa_reader
from digitalmodel.modules.catenary.catenary import Catenary
from digitalmodel.modules.orcaflex import OrcaFlexAnalysis

print("所有导入成功！")
  2. 运行测试套件
    bash
    uv run pytest tests/ -v
  3. 检查是否存在损坏的导入
    bash
    # 查找任何剩余的旧导入模式
grep -r "from digitalmodel\\." --include="*.py" . | grep -v "modules"

Plan File Archival

检查清单

—

重构前

  • Completed plan files archived to specs/archive/
  • Plan files checked for 
    status: completed
    in YAML frontmatter
  • Git工作目录干净
  • 重构前所有测试通过
  • 创建了备份分支
  • 记录了当前结构
  • 完成预检查（见预检查部分）
  • 识别了重复目录
  • 对运行时文件与配置文件进行了分类
  • 编制了隐藏文件夹清单

Benchmark Reorganization

重构期间

—

模块结构

  • Benchmark test fixtures moved to tests/fixtures/<tool_name>/
  • Benchmark generated outputs (reports/, results/) added to .gitignore
  • Empty benchmark structure maintained with .gitkeep
  • 所有模块使用
    git mv
    移动到modules/子目录
  • 创建并填充了tests/modules/
  • 创建了specs/modules/（空目录添加.gitkeep）
  • 创建了docs/modules/（空目录添加.gitkeep）
  • 创建了examples/modules/（空目录添加.gitkeep）

Post-Refactor

根级工件清理

  • __init__.py
    files created with proper exports
  • All import references updated
  • pyproject.toml
    updated if needed
  • Tests pass after refactor
  • No broken imports found
  • Git history preserved (verify with 
    git log --follow
    )
  • Post-cleanup verification completed (see Post-cleanup Verification section)
  • .gitignore updated with new patterns
  • No untracked files at root level (except intended ones)
  • 移除了日志文件（*.log）
  • 移除了临时文件（*.tmp, *.temp）
  • 移除了构建工件（dist/, build/, *.egg-info/）
  • 移除了缓存文件（pycache/, .pytest_cache/）
  • 迁移或移除了测试输出文件
  • 迁移了原型/实验代码到examples/或直接移除

Common Patterns Found During Reorganization

目录合并

Based on real-world reorganization experience, these patterns frequently appear:
  • 将agents/内容移动到.claude/agent-library/
  • 合并了重复的skill目录
  • 移除了空目录

1. Duplicate Agent Directories

隐藏文件夹检查

undefined
  • .agent-os/ - 已检查并清理（通常移除）
  • .ai/ - 已检查并清理（通常移除）
  • .drcode/ - 已检查并清理（通常移除）
  • .claude/ - 保留并整理
  • .venv/ - 确认已添加到.gitignore

Pattern: Multiple locations for agent definitions

测试输出迁移

agents/ # Root-level (often untracked) .claude/agents/ # Claude-specific .claude/agent-library/ # Preferred location .agent-os/agents/ # Legacy AI OS structure
  • HTML报告移动到tests/reports/或移除
  • 覆盖率报告移动到tests/coverage/或移除
  • 截图输出移动到tests/snapshots/或移除
  • 基准测试结果移动到tests/benchmarks/或移除

Resolution: Consolidate to .claude/agent-library/

计划文件归档

git mv agents/* .claude/agent-library/ rm -rf agents/
undefined
  • 已完成的计划文件归档到specs/archive/
  • 检查计划文件YAML前置内容中的
    status: completed

2. Scattered Runtime Data

基准测试目录重组

undefined
  • 基准测试夹具移动到tests/fixtures/<tool_name>/
  • 基准测试生成的输出（reports/, results/）添加到.gitignore
  • 使用.gitkeep维护空的基准测试结构

Pattern: Runtime data mixed with config

重构后

coordination/ # Untracked runtime state memory/ # Untracked memory store
  • 创建了带有正确导出的__init__.py文件
  • 更新了所有导入引用
  • 必要时更新了pyproject.toml
  • 重构后测试通过
  • 未发现损坏的导入
  • 保留了Git历史记录（使用
    git log --follow
    验证）
  • 完成清理后验证（见清理后验证部分）
  • 更新了.gitignore添加新模式
  • 根目录下无未跟踪文件（除了有意保留的）

Resolution:

重组期间常见模式

- Delete untracked coordination/ and memory/

—
undefined
基于实际重组经验，以下模式经常出现：

3. Untracked Artifacts in Root

1. 重复Agent目录

undefined
undefined

Pattern: Various artifacts accumulate in root

模式：Agent定义存在多个位置

*.log # Log files from various tools *.html # Test reports, visualizations _output. # Output files from scripts *.sim # Simulation files *.dat # Data files
agents/ # 根级别（通常未跟踪） .claude/agents/ # Claude特定目录 .claude/agent-library/ # 首选位置 .agent-os/agents/ # 遗留AI OS结构

Resolution:

解决方案：整合到.claude/agent-library/

- Delete if not needed

—

- Move to inputs/ or outputs/ if needed

—

- Add patterns to .gitignore

—
undefined
git mv agents/* .claude/agent-library/ rm -rf agents/
undefined

4. Multiple Skill/Command Locations

2. 分散的运行时数据

undefined
undefined

Pattern: Skills defined in multiple places

模式：运行时数据与配置混合

.claude/skills/ # Claude skills skills/ # Root-level skills .agent-os/skills/ # Legacy location commands/ # Alternative naming
coordination/ # 未跟踪的运行时状态 memory/ # 未跟踪的内存存储

Resolution: Consolidate to .claude/skills/

解决方案：

—

- 删除未跟踪的coordination/和memory/

undefined
undefined

5. Legacy Hidden Folders

3. 根目录下的未跟踪工件

undefined
undefined

Pattern: Accumulation of AI tool folders

模式：各种工件在根目录累积

.agent-os/ # Custom agent OS (usually obsolete) .ai/ # Generic AI folder .drcode/ # DR Code specific .cursor/ # Cursor editor .vscode/ # VS Code settings
*.log # 来自各种工具的日志文件 *.html # 测试报告、可视化文件 _output. # 脚本输出文件 *.sim # 仿真文件 *.dat # 数据文件

Resolution:

解决方案：

- .vscode/, .cursor/ - keep if used, add to .gitignore

- 不需要则删除

- .agent-os/, .ai/, .drcode/ - usually safe to remove

- 需要则移动到inputs/或output/

- Check for any unique configs before deleting

- 将模式添加到.gitignore

undefined
undefined

6. Test Data in Wrong Locations

4. 多个Skill/Command位置

undefined
undefined

Pattern: Test data scattered

模式：Skill在多个位置定义

tests/test_data/ # Correct location test_data/ # Root level (wrong) data/ # Ambiguous location fixtures/ # Sometimes at root
.claude/skills/ # Claude skills skills/ # 根级别skills .agent-os/skills/ # 遗留位置 commands/ # 替代命名

Resolution: Move all to tests/test_data/ or tests/fixtures/

解决方案：整合到.claude/skills/

undefined
undefined

7. Prototype Code Mixed with Production

5. 遗留隐藏文件夹

undefined
undefined

Pattern: Experimental code in src/

模式：AI工具文件夹累积

src/package/experimental/ # Should be separate src/package/prototype_.py # Should be in examples/ scripts/scratch_.py # Should be in examples/experiments/
.agent-os/ # 自定义Agent OS（通常已过时） .ai/ # 通用AI文件夹 .drcode/ # DR Code特定文件夹 .cursor/ # Cursor编辑器 .vscode/ # VS Code设置

Resolution: Move to examples/experiments/ or examples/prototypes/

解决方案：

—

- .vscode/, .cursor/ - 如果使用则保留，添加到.gitignore

—

- .agent-os/, .ai/, .drcode/ - 通常可以安全移除

—

- 删除前检查是否有唯一配置

undefined
undefined

Hidden Folder Consolidation Patterns

6. 错误位置的测试数据

When consolidating multiple hidden folders into a single authoritative location (.claude/), follow these patterns based on real-world experience.
undefined

Real-World Example: digitalmodel Repository

模式：测试数据分散

Before consolidation:
.claude/      519 tracked files (authoritative)
.agent-os/    129 tracked files (legacy)
.ai/           52 tracked files (legacy)
After consolidation:
.claude/      670 tracked files (519 + 129 + 52, minus duplicates)
tests/test_data/ # 正确位置 test_data/ # 根级别（错误） data/ # 模糊位置 fixtures/ # 有时在根目录

Merge Patterns by Content Type

解决方案：全部移动到tests/test_data/或tests/fixtures/

1. Conflicting Directories (Rename to Preserve Both)

—
bash
undefined
undefined

When both source and destination have the same directory name

7. 原型代码与生产代码混合

Pattern: Move to a subdirectory with 'legacy-' prefix

—

commands/ exists in both .agent-os/ and .claude/

—
git mv .agent-os/commands .claude/commands/legacy-scripts
undefined

hooks/ exists in both .agent-os/ and .claude/

模式：src/中存在实验代码

git mv .agent-os/hooks .claude/hooks/legacy
src/package/experimental/ # 应单独存放 src/package/prototype_.py # 应放在examples/ scripts/scratch_.py # 应放在examples/experiments/

Result: Original .claude/commands/ preserved, .agent-os/commands/ accessible at legacy-scripts/

解决方案：移动到examples/experiments/或examples/prototypes/

undefined
undefined

2. Non-Conflicting Directories (Direct Move)

隐藏文件夹整合模式

bash
undefined
将多个隐藏文件夹合并到单个权威位置（.claude/）时，根据实际经验遵循以下模式。

When destination doesn't have the directory

实际示例：digitalmodel仓库

Pattern: Direct git mv

—

standards/ only exists in .agent-os/

—
git mv .agent-os/standards .claude/standards
合并前：
.claude/      519个已跟踪文件（权威）
.agent-os/    129个已跟踪文件（遗留）
.ai/           52个已跟踪文件（遗留）
合并后：
.claude/      670个已跟踪文件（519 + 129 + 52，减去重复项）

implementation-history/ only exists in .ai/

按内容类型的合并模式

—

1. 冲突目录（重命名以保留两者）

git mv .ai/implementation-history .claude/implementation-history
bash
undefined

Result: Clean move preserving git history

当源和目标都有相同目录名称时

—

模式：移动到带有'legacy-'前缀的子目录

—

.agent-os/和.claude/中都有commands/

undefined
git mv .agent-os/commands .claude/commands/legacy-scripts

3. Mergeable Directories (Combine Content)

.agent-os/和.claude/中都有hooks/

bash
undefined
git mv .agent-os/hooks .claude/hooks/legacy

When both have the same directory with different files

结果：保留原始.claude/commands/，.agent-os/commands/可在legacy-scripts/访问

Pattern: Move individual files or use merge strategy

—

docs/ has different files in each location

—
git mv .agent-os/docs/unique-file.md .claude/docs/ git mv .ai/docs/another-file.md .claude/docs/
undefined

Or merge entire directories (may require manual review)

2. 无冲突目录（直接移动）

cp -r .agent-os/docs/* .claude/docs/ git add .claude/docs/ git rm -r .agent-os/docs/
undefined
bash
undefined

4. Conflicting Files (Rename with Suffix)

当目标没有该目录时

—

模式：直接使用git mv

—

standards/仅存在于.agent-os/

bash
undefined
git mv .agent-os/standards .claude/standards

When same filename exists in multiple locations

implementation-history/仅存在于.ai/

Pattern: Rename with source identifier

—

README.md exists in .claude/, .agent-os/, and .ai/

—
git mv .agent-os/README.md .claude/README-agent-os-legacy.md git mv .ai/README.md .claude/README-ai-legacy.md
git mv .ai/implementation-history .claude/implementation-history

Or use descriptive names

结果：干净移动，保留Git历史

git mv .agent-os/README.md .claude/docs/agent-os-overview.md git mv .ai/README.md .claude/docs/ai-folder-overview.md
undefined
undefined

Consolidation Checklist

3. 可合并目录（合并内容）

  • Count files in each source folder: 
    git ls-files <dir> | wc -l
  • Identify overlapping directory names
  • Identify overlapping file names
  • Create merge plan with conflict resolution strategy
  • Execute moves in parallel per source folder
  • Verify no files were lost: compare totals
  • Remove empty source folders
  • Update any references to old paths
  • Commit with descriptive message noting file counts
bash
undefined

Common Consolidation Scenarios

当两者有相同目录但文件不同时

—

模式：移动单个文件或使用合并策略

—

docs/在每个位置有不同文件

ScenarioSourceDestinationStrategy
Duplicate commands.agent-os/commands/.claude/commands/legacy-scripts/Rename
Duplicate hooks.agent-os/hooks/.claude/hooks/legacy/Rename
Unique standards.agent-os/standards/.claude/standards/Direct move
Unique history.ai/implementation-history/.claude/implementation-history/Direct move
Overlapping docs.agent-os/docs/.claude/docs/Merge content
Conflicting README.agent-os/README.md.claude/README-legacy.mdRename
git mv .agent-os/docs/unique-file.md .claude/docs/ git mv .ai/docs/another-file.md .claude/docs/

Metrics Tracking

或合并整个目录（可能需要手动检查）

Track quantitative metrics throughout the consolidation process to verify completeness and document changes.
cp -r .agent-os/docs/* .claude/docs/ git add .claude/docs/ git rm -r .agent-os/docs/
undefined

Pre-consolidation Metrics

4. 冲突文件（添加后缀重命名）

bash
undefined
bash
undefined

Capture baseline metrics before any changes

当多个位置存在相同文件名时

—

模式：添加源标识符重命名

—

.claude/, .agent-os/, 和.ai/中都有README.md

echo "=== Pre-consolidation File Counts ===" echo ".claude/: $(git ls-files .claude/ | wc -l) files" echo ".agent-os/: $(git ls-files .agent-os/ | wc -l) files" echo ".ai/: $(git ls-files .ai/ | wc -l) files" echo "Total: $(git ls-files .claude/ .agent-os/ .ai/ | wc -l) files"
git mv .agent-os/README.md .claude/README-agent-os-legacy.md git mv .ai/README.md .claude/README-ai-legacy.md

Save to file for comparison

或使用描述性名称

git ls-files .claude/ .agent-os/ .ai/ | wc -l > /tmp/pre_consolidation_count.txt
undefined
git mv .agent-os/README.md .claude/docs/agent-os-overview.md git mv .ai/README.md .claude/docs/ai-folder-overview.md
undefined

Post-consolidation Verification

整合检查清单

bash
undefined
  • 统计每个源文件夹的文件数：
    git ls-files <dir> | wc -l
  • 识别重叠目录名称
  • 识别重叠文件名
  • 创建带有冲突解决策略的合并计划
  • 按源文件夹并行执行移动
  • 验证无文件丢失：比较总数
  • 移除空源文件夹
  • 更新任何对旧路径的引用
  • 使用描述性提交消息记录文件数

Verify file counts after consolidation

常见整合场景

echo "=== Post-consolidation File Counts ===" echo ".claude/: $(git ls-files .claude/ | wc -l) files"
场景源目标策略
重复commands.agent-os/commands/.claude/commands/legacy-scripts/重命名
重复hooks.agent-os/hooks/.claude/hooks/legacy/重命名
唯一standards.agent-os/standards/.claude/standards/直接移动
唯一history.ai/implementation-history/.claude/implementation-history/直接移动
重叠docs.agent-os/docs/.claude/docs/合并内容
冲突README.agent-os/README.md.claude/README-legacy.md重命名

Compare to expected total

指标跟踪

expected=$(cat /tmp/pre_consolidation_count.txt) actual=$(git ls-files .claude/ | wc -l) echo "Expected: $expected files" echo "Actual: $actual files"
if [ "$actual" -ge "$expected" ]; then echo "SUCCESS: All files accounted for" else echo "WARNING: $(($expected - $actual)) files may be missing" fi
undefined
在整合过程中跟踪量化指标，以验证完整性并记录变更。

Git Commit Metrics

整合前指标

bash
undefined
bash
undefined

Check what the commit will include

在进行任何变更前捕获基准指标

git diff --stat --staged
echo "=== 整合前文件计数 ===" echo ".claude/: $(git ls-files .claude/ | wc -l) 个文件" echo ".agent-os/: $(git ls-files .agent-os/ | wc -l) 个文件" echo ".ai/: $(git ls-files .ai/ | wc -l) 个文件" echo "总计: $(git ls-files .claude/ .agent-os/ .ai/ | wc -l) 个文件"

Example output:

保存到文件以便比较

181 files changed, 2847 insertions(+), 1523 deletions(-)

—

The numbers indicate:

—

- files changed: Total files moved/renamed

—

- insertions: Lines added (includes moved content)

—

- deletions: Lines removed (includes content moved from old location)

—
undefined
git ls-files .claude/ .agent-os/ .ai/ | wc -l > /tmp/pre_consolidation_count.txt
undefined

Metrics Documentation Template

整合后验证

Document consolidation metrics in commit message or notes:
markdown
undefined
bash
undefined

Consolidation Metrics

验证整合后的文件计数

Operation: Hidden folder consolidation to .claude/
File Counts:
  • Before: .claude/ (519) + .agent-os/ (129) + .ai/ (52) = 700 total
  • After: .claude/ (670 files)
  • Difference: 30 files were duplicates/merged
Git Stats: 181 files changed, +2847/-1523 lines
Decisions Made:
  • Moved: 151 files (no conflicts)
  • Renamed: 25 files (conflict resolution)
  • Merged: 5 files (content combined)
  • Deleted: 0 files (none removed)
Source Folders Removed:
  • .agent-os/ (fully merged)
  • .ai/ (fully merged)
undefined
echo "=== 整合后文件计数 ===" echo ".claude/: $(git ls-files .claude/ | wc -l) 个文件"

Tracking Delete vs Move Decisions

与预期总数比较

bash
undefined
expected=$(cat /tmp/pre_consolidation_count.txt) actual=$(git ls-files .claude/ | wc -l) echo "预期: $expected 个文件" echo "实际: $actual 个文件"
if [ "$actual" -ge "$expected" ]; then echo "成功：所有文件已统计" else echo "警告：可能丢失了$(($expected - $actual))个文件" fi
undefined

Create a decision log during consolidation

Git提交指标

cat > consolidation_log.md << 'EOF'
bash
undefined

Consolidation Decision Log

检查提交将包含的内容

File/DirectoryActionReason
.agent-os/commands/MOVED to .claude/commands/legacy-scripts/Conflict with existing
.agent-os/standards/MOVED to .claude/standards/No conflict
.agent-os/temp/DELETEDRuntime data, not needed
.ai/implementation-history/MOVED to .claude/implementation-history/Unique valuable content
.ai/.cache/DELETEDCache data, regenerated
EOF
git diff --stat --staged

Track in git for documentation

示例输出：

—

181个文件变更，2847行插入(+)，1523行删除(-)

—

数字含义：

—

- files changed: 移动/重命名的文件总数

—

- insertions: 添加的行数（包括移动的内容）

—

- deletions: 删除的行数（包括从旧位置移动的内容）

git add consolidation_log.md
undefined
undefined

Post-cleanup Verification

指标文档模板

1. Import Verification for Python Modules

—
bash
undefined
在提交消息或笔记中记录整合指标：
markdown
undefined

Create a verification script

整合指标

cat > verify_imports.py << 'EOF' #!/usr/bin/env python """Verify all imports work after reorganization.""" import sys from pathlib import Path
操作：将隐藏文件夹整合到.claude/
文件计数:
  • 之前：.claude/ (519) + .agent-os/ (129) + .ai/ (52) = 总计700个
  • 之后：.claude/ (670个文件)
  • 差异：30个文件为重复项/已合并
Git统计：181个文件变更，+2847/-1523行
决策记录:
  • 移动：151个文件（无冲突）
  • 重命名：25个文件（冲突解决）
  • 合并：5个文件（内容合并）
  • 删除：0个文件（无文件被移除）
已移除源文件夹:
  • .agent-os/（完全合并）
  • .ai/（完全合并）
undefined

Add src to path

跟踪删除与移动决策

sys.path.insert(0, str(Path(file).parent / "src"))
bash
undefined

Test all module imports

在整合过程中创建决策日志

modules_to_test = [ "digitalmodel", "digitalmodel.modules", "digitalmodel.modules.aqwa", "digitalmodel.modules.catenary", "digitalmodel.modules.orcaflex", "digitalmodel.modules.mooring", "digitalmodel.modules.fea_model", "digitalmodel.modules.pipe_capacity", ]
failed = [] for module in modules_to_test: try: import(module) print(f"✓ {module}") except ImportError as e: print(f"✗ {module}: {e}") failed.append(module)
if failed: print(f"\n{len(failed)} imports failed!") sys.exit(1) else: print(f"\nAll {len(modules_to_test)} imports successful!") EOF
cat > consolidation_log.md << 'EOF'

Run verification

整合决策日志

uv run python verify_imports.py
undefined
文件/目录操作原因
.agent-os/commands/移动到.claude/commands/legacy-scripts/与现有目录冲突
.agent-os/standards/移动到.claude/standards/无冲突
.agent-os/temp/删除运行时数据，无需保留
.ai/implementation-history/移动到.claude/implementation-history/有价值的唯一内容
.ai/.cache/删除缓存数据，可重新生成
EOF

2. Git Status Review

提交到Git作为文档

bash
undefined
git add consolidation_log.md
undefined

Check for any unintended changes

清理后验证

—

1. Python模块导入验证

git status
bash
undefined

Verify no broken file references

创建验证脚本

git diff --name-status
cat > verify_imports.py << 'EOF' #!/usr/bin/env python """验证重组后所有导入是否正常工作。""" import sys from pathlib import Path

Check for files that should be tracked but aren't

将src添加到路径

git ls-files --others --exclude-standard
sys.path.insert(0, str(Path(file).parent / "src"))

Verify history preservation for moved files

测试所有模块导入

git log --follow --oneline -- src/digitalmodel/modules/aqwa/aqwa_reader.py
undefined
modules_to_test = [ "digitalmodel", "digitalmodel.modules", "digitalmodel.modules.aqwa", "digitalmodel.modules.catenary", "digitalmodel.modules.orcaflex", "digitalmodel.modules.mooring", "digitalmodel.modules.fea_model", "digitalmodel.modules.pipe_capacity", ]
failed = [] for module in modules_to_test: try: import(module) print(f"✓ {module}") except ImportError as e: print(f"✗ {module}: {e}") failed.append(module)
if failed: print(f"
{len(failed)}个导入失败！") sys.exit(1) else: print(f"
所有{len(modules_to_test)}个导入成功！") EOF

3. Directory Structure Validation

运行验证

bash
undefined
uv run python verify_imports.py
undefined

Verify target structure exists

2. Git状态检查

echo "=== Source Modules ===" ls -la src/digitalmodel/modules/
echo "=== Test Modules ===" ls -la tests/modules/
echo "=== Spec Modules ===" ls -la specs/modules/
echo "=== Doc Modules ===" ls -la docs/modules/
echo "=== Example Modules ===" ls -la examples/modules/
bash
undefined

Verify no modules remain at old locations

检查是否有意外变更

echo "=== Check for stragglers ===" ls src/digitalmodel/ | grep -v "modules|__|.py"
undefined
git status

4. Test Suite Execution

验证无损坏的文件引用

bash
undefined
git diff --name-status

Run full test suite

检查应被跟踪但未跟踪的文件

uv run pytest tests/ -v
git ls-files --others --exclude-standard

Run with coverage to verify all code is reachable

验证移动文件的历史记录保留情况

uv run pytest tests/ --cov=src/digitalmodel --cov-report=term-missing
git log --follow --oneline -- src/digitalmodel/modules/aqwa/aqwa_reader.py
undefined

Run specific module tests

3. 目录结构验证

uv run pytest tests/modules/aqwa/ -v
undefined
bash
undefined

5. Clean Root Verification

验证目标结构存在

bash
undefined
echo "=== 源模块 ===" ls -la src/digitalmodel/modules/
echo "=== 测试模块 ===" ls -la tests/modules/
echo "=== 规格模块 ===" ls -la specs/modules/
echo "=== 文档模块 ===" ls -la docs/modules/
echo "=== 示例模块 ===" ls -la examples/modules/

List root directory contents - should be minimal

验证无模块遗留旧位置

ls -la | grep -v "^d" | grep -v "^."
echo "=== 检查遗留文件 ===" ls src/digitalmodel/ | grep -v "modules\|__\|\.py"
undefined

Expected root files:

4. 测试套件执行

- pyproject.toml

—

- README.md

—

- LICENSE

—

- .gitignore

—

- CLAUDE.md (optional)

—

Anything else should be questioned

—
undefined
bash
undefined

6. Gitignore Verification

运行完整测试套件

bash
undefined
uv run pytest tests/ -v

Check .gitignore has all necessary patterns

运行覆盖率检查以验证所有代码可访问

Recommended patterns to add:

—

*.log

—

*.tmp

—

pycache/

—

.pytest_cache/

—

dist/

—

build/

—

*.egg-info/

—

.coverage

—

htmlcov/

—
undefined
uv run pytest tests/ --cov=src/digitalmodel --cov-report=term-missing

Common Issues and Solutions

运行特定模块测试

Issue: Circular imports after refactor

—
Solution: Use lazy imports or restructure dependencies
python
undefined
uv run pytest tests/modules/aqwa/ -v
undefined

Use TYPE_CHECKING for type hints only

5. 根目录清理验证

from typing import TYPE_CHECKING if TYPE_CHECKING: from digitalmodel.modules.other import OtherClass
undefined
bash
undefined

Issue: Relative imports broken

列出根目录内容 - 应尽量精简

Solution: Convert to absolute imports
python
undefined
ls -la | grep -v "^d" | grep -v "^\."

Before (relative)

预期根文件：

—

- pyproject.toml

—

- README.md

—

- LICENSE

—

- .gitignore

—

- CLAUDE.md（可选）

—

其他任何文件都应检查

from .utils import helper
undefined

After (absolute)

6. Gitignore验证

from digitalmodel.modules.mymodule.utils import helper
undefined
bash
undefined

Issue: Test discovery fails

检查.gitignore包含所有必要模式

—

建议添加的模式：

—

*.log

—

*.tmp

—

pycache/

—

.pytest_cache/

—

dist/

—

build/

—

*.egg-info/

—

.coverage

—

htmlcov/

Solution: Ensure conftest.py at tests/modules/ level
python
undefined
undefined

tests/modules/conftest.py

常见问题与解决方案

—

问题：重构后出现循环导入

import sys from pathlib import Path
解决方案：使用延迟导入或重构依赖关系
python
undefined

Add src to path for imports

仅为类型提示使用TYPE_CHECKING

src_path = Path(file).parent.parent.parent / "src" sys.path.insert(0, str(src_path))
undefined
from typing import TYPE_CHECKING if TYPE_CHECKING: from digitalmodel.modules.other import OtherClass
undefined

Issue: Package not found after move

问题：相对导入损坏

Solution: Update pyproject.toml package discovery
toml
[tool.setuptools.packages.find]
where = ["src"]
include = ["digitalmodel*"]
解决方案：转换为绝对导入
python
undefined

Best Practices

之前（相对）

  1. Commit frequently - Make small, focused commits for each module moved
  2. Use feature branch - Create 
    refactor/module-structure
    branch
  3. Update documentation - Update README.md and any architecture docs
  4. Communicate changes - If team project, document breaking changes
  5. Run full test suite - Verify all tests pass before merging
from .utils import helper

Related Skills

之后（绝对）

  • context-management - Managing context during large refactors
  • session-start-routine - Session initialization
from digitalmodel.modules.mymodule.utils import helper
undefined

References

问题：测试发现失败

解决方案：确保tests/modules/层级有conftest.py
python
undefined

Cleanup Categories Quick Reference

tests/modules/conftest.py

CategoryExamplesAction
Root-level artifacts*.log, *.tmp, *.htmlDelete or move to outputs/
Build artifactsdist/, build/, *.egg-infoDelete (regenerated on build)
Cache filespycache/, .pytest_cache/Delete and .gitignore
Duplicate dirsagents/, .claude/agents/Consolidate to .claude/agent-library/
Legacy hidden.agent-os/, .ai/, .drcode/Review and usually delete
Test outputsreports/, coverage/, snapshots/Move under tests/
Prototype codescratch_*.py, experimental/Move to examples/
Test data*.csv, *.json at rootMove to tests/test_data/
Config files*.yaml, *.toml, *.jsonKeep at root or move to config/
Benchmark fixtureslegacy test data filesMove to tests/fixtures/<tool_name>/
Benchmark outputstimestamped reports/resultsAdd to .gitignore
Completed plansstatus: completed in frontmatterArchive to specs/archive/
import sys from pathlib import Path

Benchmark Directory Reorganization

添加src到路径以便导入

Benchmark directories often contain mixed content: test fixtures that should be tracked vs generated outputs that should be ignored.
src_path = Path(file).parent.parent.parent / "src" sys.path.insert(0, str(src_path))
undefined

Pattern: Separate Tracked Fixtures from Gitignored Outputs

问题：移动后找不到包

bash
undefined
解决方案：更新pyproject.toml的包发现配置
toml
[tool.setuptools.packages.find]
where = ["src"]
include = ["digitalmodel*"]

1. Identify benchmark content types

最佳实践

ls -la benchmarks/
  1. 频繁提交 - 为每个移动的模块创建小而专注的提交
  2. 使用功能分支 - 创建
    refactor/module-structure
    分支
  3. 更新文档 - 更新README.md和任何架构文档
  4. 沟通变更 - 如果是团队项目，记录破坏性变更
  5. 运行完整测试套件 - 合并前验证所有测试通过

Common benchmark content:

相关技能

- legacy_projects/ -> Test fixtures (track in git)

—

- reports/ -> Generated HTML reports (gitignore)

—

- results/ -> Generated CSV/JSON results (gitignore)

—

2. Move test fixtures to tests/fixtures/

—
git mv benchmarks/legacy_projects/ tests/fixtures/orcaflex/
  • context-management - 大型重构期间的上下文管理
  • session-start-routine - 会话初始化

3. Add generated output directories to .gitignore

参考资料

cat >> .gitignore << 'EOF'

Benchmark generated outputs

清理类别快速参考

benchmarks/reports/ benchmarks/results/ EOF
类别示例操作
根级工件*.log, *.tmp, *.html删除或移动到outputs/
构建工件dist/, build/, *.egg-info删除（构建时可重新生成）
缓存文件pycache/, .pytest_cache/删除并添加到.gitignore
重复目录agents/, .claude/agents/整合到.claude/agent-library/
遗留隐藏文件夹.agent-os/, .ai/, .drcode/检查并通常删除
测试输出reports/, coverage/, snapshots/移动到tests/下
原型代码scratch_*.py, experimental/移动到examples/
测试数据根目录下的*.csv, *.json移动到tests/test_data/
配置文件*.yaml, *.toml, *.json保留在根目录或移动到config/
基准测试夹具遗留测试数据文件移动到tests/fixtures/<tool_name>/
基准测试输出带时间戳的reports/results/添加到.gitignore
已完成计划前置内容中status: completed归档到specs/archive/

4. Create .gitkeep for empty benchmark structure

基准测试目录重组

mkdir -p benchmarks/reports benchmarks/results touch benchmarks/.gitkeep
undefined
基准测试目录通常包含混合内容：应被跟踪的测试夹具与应被忽略的生成输出。

Benchmark Content Classification

模式：将跟踪的夹具与Git忽略的输出分离

Content TypeExamplesAction
Test fixtureslegacy_projects/.dat, reference_data/.csv
git mv
to tests/fixtures/<tool_name>/
Generated reportsreport_YYYYMMDD.html, benchmark.htmlAdd to .gitignore
Generated resultsresults_YYYYMMDD.csv, output_*.jsonAdd to .gitignore
Benchmark scriptsrun_benchmarks.py, compare_results.pyKeep in benchmarks/ or scripts/benchmarks/
bash
undefined

Example: OrcaFlex Benchmark Reorganization

1. 识别基准测试内容类型

bash
undefined
ls -la benchmarks/

Before:

常见基准测试内容：

—

- legacy_projects/ -> 测试夹具（在Git中跟踪）

—

- reports/ -> 生成的HTML报告（Git忽略）

—

- results/ -> 生成的CSV/JSON结果（Git忽略）

—

2. 将测试夹具移动到tests/fixtures/

benchmarks/ ├── legacy_projects/ # Test fixture OrcaFlex files (tracked) │ ├── model1.dat │ └── model2.dat ├── reports/ # Generated HTML reports (untracked) │ └── benchmark_20260120.html └── results/ # Generated CSV results (untracked) └── results_20260120.csv
git mv benchmarks/legacy_projects/ tests/fixtures/orcaflex/

After:

3. 将生成的输出目录添加到.gitignore

tests/fixtures/orcaflex/ # Moved from benchmarks/legacy_projects/ ├── model1.dat └── model2.dat
benchmarks/ # Clean benchmark directory ├── .gitkeep ├── reports/ # .gitignore'd └── results/ # .gitignore'd
undefined
cat >> .gitignore << 'EOF'

Complete Refactor Session Workflow

基准测试生成的输出

A full repository refactor typically follows this 4-phase workflow. Each phase should be committed separately for clean git history and easy rollback.
benchmarks/reports/ benchmarks/results/ EOF

Phase 1: Module Reorganization

4. 为空白基准测试结构创建.gitkeep

Move code to the 5-layer module-based architecture.
bash
undefined
mkdir -p benchmarks/reports benchmarks/results touch benchmarks/.gitkeep
undefined

1a. Move source modules

基准测试内容分类

git mv src/<pkg>/<module> src/<pkg>/modules/<module>
内容类型示例操作
测试夹具legacy_projects/.dat, reference_data/.csv
git mv
到tests/fixtures/<tool_name>/
生成的报告report_YYYYMMDD.html, benchmark.html添加到.gitignore
生成的结果results_YYYYMMDD.csv, output_*.json添加到.gitignore
基准测试脚本run_benchmarks.py, compare_results.py保留在benchmarks/或scripts/benchmarks/

1b. Move tests

示例：OrcaFlex基准测试重组

git mv tests/<module> tests/modules/<module>
bash
undefined

1c. Move specs

之前：

git mv specs/<module> specs/modules/<module>
benchmarks/ ├── legacy_projects/ # 测试夹具OrcaFlex文件（已跟踪） │ ├── model1.dat │ └── model2.dat ├── reports/ # 生成的HTML报告（未跟踪） │ └── benchmark_20260120.html └── results/ # 生成的CSV结果（未跟踪） └── results_20260120.csv

1d. Update imports across codebase

之后：

find . -name "*.py" -exec sed -i 's/from <pkg>.<module>/from <pkg>.modules.<module>/g' {} ;
tests/fixtures/orcaflex/ # 从benchmarks/legacy_projects/移动而来 ├── model1.dat └── model2.dat
benchmarks/ # 清理后的基准测试目录 ├── .gitkeep ├── reports/ # 已添加到.gitignore └── results/ # 已添加到.gitignore
undefined

1e. Commit Phase 1

完整重构会话工作流

git commit -m "refactor: Reorganize repository to module-based 5-layer architecture"
undefined
完整的仓库重构通常遵循以下4阶段工作流。每个阶段应单独提交，以保持清晰的Git历史并便于回滚。

Phase 2: Hidden Folder Consolidation

阶段1：模块重组

Merge legacy AI/agent folders into 
.claude/
.
bash
undefined
将代码移动到基于模块的5层架构。
bash
undefined

2a. Consolidate .agent-os/ + .ai/ into .claude/

1a. 移动源模块

Example: 519 + 129 + 52 = 670 files after merge

—
git mv .agent-os/commands .claude/commands/legacy-scripts git mv .agent-os/standards .claude/standards git mv .ai/implementation-history .claude/implementation-history
git mv src/<pkg>/<module> src/<pkg>/modules/<module>

2b. Delete dead folders

1b. 移动测试文件

rm -rf .agent-runtime .common .specify
git mv tests/<module> tests/modules/<module>

2c. Commit Phase 2

1c. 移动规格文件

git commit -m "refactor: Consolidate .agent-os + .ai into .claude (670 files)"
undefined
git mv specs/<module> specs/modules/<module>

Phase 3: Final Cleanup

1d. 更新整个代码库的导入

Remove legacy configurations and consolidate scripts.
bash
undefined
find . -name "*.py" -exec sed -i 's/from <pkg>.<module>/from <pkg>.modules.<module>/g' {} \;

3a. Delete legacy config folders

1e. 提交阶段1

rm -rf .drcode/ # Legacy AI config (confirmed deletable) rm -rf .benchmarks/ # Empty benchmark folder
git commit -m "refactor: Reorganize repository to module-based 5-layer architecture"
undefined

3b. Consolidate scripts

阶段2：隐藏文件夹整合

git mv .git-commands/* scripts/git/ rm -rf .git-commands/
将遗留AI/agent文件夹合并到
.claude/
。
bash
undefined

3c. Move registries to docs

2a. 将.agent-os/ + .ai/整合到.claude/

—

示例：519 + 129 + 52 = 合并后670个文件

git mv .slash-commands/* .claude/docs/commands/ rm -rf .slash-commands/
git mv .agent-os/commands .claude/commands/legacy-scripts git mv .agent-os/standards .claude/standards git mv .ai/implementation-history .claude/implementation-history

3d. Commit Phase 3

2b. 删除无用文件夹

git commit -m "chore: Delete legacy config and consolidate scripts"
undefined
rm -rf .agent-runtime .common .specify

Phase 4: Documentation and Archival

2c. 提交阶段2

Update README and skill documentation with learnings. Archive completed plans.
bash
undefined
git commit -m "refactor: Consolidate .agent-os + .ai into .claude (670 files)"
undefined

4a. Update README structure section

阶段3：最终清理

- Document new module-based architecture

—

- Remove references to deleted folders

—

4b. Update skills with session learnings

—

- Add new patterns discovered

—

- Update version numbers

—

- Add changelog entries

—

4c. Archive completed plan files

—

Check plan files in specs/modules/ for status: completed in YAML frontmatter

—

Move completed plans to specs/archive/ to keep specs/modules/ clean

—
git mv specs/modules/<completed-plan>.md specs/archive/
移除遗留配置并整合脚本。
bash
undefined

4d. Commit Phase 4

3a. 删除遗留配置文件夹

git commit -m "docs: Update README structure and skill documentation"
undefined
rm -rf .drcode/ # 遗留AI配置（确认可删除） rm -rf .benchmarks/ # 空基准测试文件夹

Plan File Archival Pattern

3b. 整合脚本

Completed plans in 
specs/modules/
should be archived to maintain a clean working directory.
bash
undefined
git mv .git-commands/* scripts/git/ rm -rf .git-commands/

Check plan file YAML frontmatter for completion status

3c. 将注册表移动到文档

grep -l "status: completed" specs/modules/*.md
git mv .slash-commands/* .claude/docs/commands/ rm -rf .slash-commands/

Archive completed plans using git mv to preserve history

3d. 提交阶段3

git mv specs/modules/<completed-plan>.md specs/archive/
git commit -m "chore: Delete legacy config and consolidate scripts"
undefined

Example: Archive a completed refactor plan

阶段4：文档与归档

git mv specs/modules/module-based-refactor-plan.md specs/archive/
更新README和技能文档，记录经验。归档已完成的计划。
bash
undefined

Verify archive directory exists

4a. 更新README结构部分

—

- 记录新的基于模块的架构

—

- 移除对已删除文件夹的引用

—

4b. 更新技能文档，添加会话经验

—

- 添加发现的新模式

—

- 更新版本号

—

- 添加变更日志条目

—

4c. 归档已完成的计划文件

—

检查specs/modules/中的计划文件YAML前置内容是否有status: completed

—

将已完成计划移动到specs/archive/以保持specs/modules/整洁

mkdir -p specs/archive

**When to Archive:**
- Plan file has `status: completed` in YAML frontmatter
- All tasks in the plan have been implemented and verified
- The refactor session is complete and committed
git mv specs/modules/<completed-plan>.md specs/archive/

Commit Strategy: Atomic Commits Per Phase

4d. 提交阶段4

PhaseCommit Message PatternScope
1
refactor: Reorganize repository to module-based 5-layer architecture
src, tests, specs, imports
2
refactor: Consolidate <folders> into .claude (N files)
Hidden folder merges
3
chore: Delete legacy config and consolidate scripts
Cleanup operations
4
docs: Update README structure and skill documentation
Documentation updates
Benefits of Atomic Commits:
  • Easy to review changes in each phase
  • Simple rollback if issues discovered
  • Clear git history for future reference
  • Supports incremental verification after each phase
git commit -m "docs: Update README structure and skill documentation"
undefined

Quick Start Commands

计划文件归档模式

bash
undefined
specs/modules/
中的已完成计划应归档，以保持工作目录整洁。
bash
undefined

1. Pre-flight check (run first)

检查计划文件YAML前置内容的完成状态

git status && git ls-files --others --exclude-standard | wc -l
grep -l "status: completed" specs/modules/*.md

2. Find all hidden folders

使用git mv归档已完成计划以保留历史

ls -la .* 2>/dev/null | grep "^d"
git mv specs/modules/<completed-plan>.md specs/archive/

3. Find duplicates

示例：归档已完成的重构计划

find . -type d -name "agents" -o -name "skills" -o -name "memory" 2>/dev/null
git mv specs/modules/module-based-refactor-plan.md specs/archive/

4. Find artifacts at root

验证归档目录存在

ls *.log *.tmp *.html *.sim 2>/dev/null
mkdir -p specs/archive

**归档时机：**
- 计划文件YAML前置内容中有`status: completed`
- 计划中的所有任务已实现并验证
- 重构会话已完成并提交

5. Create module structure

提交策略：按阶段原子提交

mkdir -p src/<pkg>/modules tests/modules specs/modules docs/modules examples/modules
阶段提交消息模式范围
1
refactor: Reorganize repository to module-based 5-layer architecture
src, tests, specs, imports
2
refactor: Consolidate <folders> into .claude (N files)
隐藏文件夹合并
3
chore: Delete legacy config and consolidate scripts
清理操作
4
docs: Update README structure and skill documentation
文档更新
原子提交的好处：
  • 便于检查每个阶段的变更
  • 发现问题时易于回滚
  • 为未来参考提供清晰的Git历史
  • 支持每个阶段后的增量验证

6. Archive completed plan files

快速开始命令

git mv specs/modules/<completed-plan>.md specs/archive/
bash
undefined

7. Verify after cleanup

1. 预检查（首先运行）

uv run pytest tests/ -v && git status

---
git status && git ls-files --others --exclude-standard | wc -l

Version History

2. 查找所有隐藏文件夹

  • 3.2.0 (2026-01-20): Added Plan File Archival and Benchmark Reorganization patterns
    • Added Plan File Archival pattern to archive completed plans to specs/archive/
    • Added Benchmark Directory Reorganization pattern for separating fixtures from outputs
    • Added benchmark-related gitignore patterns (reports/, results/)
    • Updated checklist with plan archival and benchmark reorganization items
    • Updated Quick Start Commands with plan archival command
    • Updated Phase 4 to include archival step
  • 3.1.0 (2026-01-20): Added Complete Refactor Session Workflow
    • Added 4-phase workflow documentation (Module Reorganization, Hidden Folder Consolidation, Final Cleanup, Documentation)
    • Added Commit Strategy section with atomic commits per phase pattern
    • Documented real-world session flow with specific examples
    • Added benefits of atomic commits for review, rollback, and history
  • 3.0.0 (2026-01-20): Major update with hidden folder consolidation patterns
    • Added Pre-consolidation Analysis section for analyzing hidden folder overlaps
    • Added Hidden Folder Consolidation Patterns section with real-world examples
    • Added Phase 3.5: Hidden Folder Consolidation to Parallel Execution Strategy
    • Added Metrics Tracking section for quantitative verification
    • Added merge patterns: Conflicting Directories, Non-Conflicting Directories, Mergeable Directories, Conflicting Files
    • Added Consolidation Checklist and Common Consolidation Scenarios table
    • Added Metrics Documentation Template for commit messages
    • Updated Parallel vs Sequential Decision Matrix with hidden folder consolidation
    • Real-world example: .agent-os/ (129 files) + .ai/ (52 files) merged into .claude/ (519 -> 670 files)
  • 2.0.0 (2025-01-20): Major update with comprehensive cleanup categories
    • Added Pre-flight Checks section
    • Added Parallel Execution Strategy with agent spawn patterns
    • Added Common Patterns Found During Reorganization
    • Added Post-cleanup Verification section
    • Expanded Checklist with cleanup categories
    • Added Quick Reference tables and Quick Start commands
  • 1.0.0 (2025-01-19): Initial release based on digitalmodel repository refactor experience
ls -la .* 2>/dev/null | grep "^d"
—

3. 查找重复项

—
find . -type d -name "agents" -o -name "skills" -o -name "memory" 2>/dev/null
—

4. 查找根目录下的工件

—
ls *.log *.tmp *.html *.sim 2>/dev/null
—

5. 创建模块结构

—
mkdir -p src/<pkg>/modules tests/modules specs/modules docs/modules examples/modules
—

6. 归档已完成计划文件

—
git mv specs/modules/<completed-plan>.md specs/archive/
—

7. 清理后验证

—
uv run pytest tests/ -v && git status

---
—

版本历史

—
  • 3.2.0 (2026-01-20): 添加计划文件归档和基准测试重组模式
    • 添加计划文件归档模式，将已完成计划归档到specs/archive/
    • 添加基准测试目录重组模式，分离夹具与输出
    • 添加基准测试相关的gitignore模式（reports/, results/）
    • 更新检查清单，添加计划归档和基准测试重组项
    • 更新快速开始命令，添加计划归档命令
    • 更新阶段4以包含归档步骤
  • 3.1.0 (2026-01-20): 添加完整重构会话工作流
    • 添加4阶段工作流文档（模块重组、隐藏文件夹整合、最终清理、文档）
    • 添加提交策略部分，包含按阶段原子提交模式
    • 记录带具体示例的实际会话流程
    • 添加原子提交在检查、回滚和历史记录方面的好处
  • 3.0.0 (2026-01-20): 重大更新，添加隐藏文件夹整合模式
    • 添加合并前分析部分，分析隐藏文件夹重叠
    • 添加隐藏文件夹整合模式部分，带实际示例
    • 在并行执行策略中添加阶段3.5：隐藏文件夹整合
    • 添加指标跟踪部分，用于量化验证
    • 添加合并模式：冲突目录、无冲突目录、可合并目录、冲突文件
    • 添加整合检查清单和常见整合场景表
    • 添加提交消息的指标文档模板
    • 更新并行与串行决策矩阵，添加隐藏文件夹整合
    • 实际示例：.agent-os/（129个文件） + .ai/（52个文件）合并到.claude/（519 -> 670个文件）
  • 2.0.0 (2025-01-20): 重大更新，添加全面清理类别
    • 添加预检查部分
    • 添加带agent生成模式的并行执行策略
    • 添加重组期间常见模式
    • 添加清理后验证部分
    • 扩展检查清单，添加清理类别
    • 添加快速参考表和快速开始命令
  • 1.0.0 (2025-01-19): 初始版本，基于digitalmodel仓库重构经验 ",