Managing Shared Project Assets Across Multiple AI Coding Assistants

The Real Problem: Copying Files Creates Divergence, Not Migration

Projects that rely heavily on AI coding assistants often accumulate a significant amount of non-code assets over time: entry-point rule files, cross-session long-term memory, current task lists, records of pitfalls encountered, business knowledge bases, reusable workflows, and auxiliary scripts. The true value of these assets lies not in the files themselves, but in their continuous evolution.

If you simply copy the entire configuration directory for use with another tool, you might achieve “migration” in a minute on the surface. In reality, however, you have created a classic engineering problem: the same data now exists in two copies, with no synchronization mechanism in place.

The consequences are predictable:

• You update an architectural convention in Tool A’s rules today, and days later forget to sync it to Tool B.
• The two tools accumulate divergent memories, and their understanding of “where the project stands” gradually drifts apart.
• A lesson learned about a past pitfall only takes effect on one side, while the other side repeats the same mistake.

This is not compatibility; this is forking. Over time, the two sets of assets will develop ever-growing discrepancies regarding the same project. Eventually, you are forced to abandon one set, rendering the migration a failure.

Step One: Distinguish What You Are Actually Migrating

Before making any changes, you must categorize the contents of your project into two distinct groups.

Category One: Project Assets (Should Be Shared)

These items fundamentally do not belong to any specific tool; they just happen to be stored within a particular tool’s directory:

• Project specifications, architectural conventions, coding style guides
• Long-term memory, current task lists, decision records, pitfall logs
• Business knowledge bases, domain terminology glossaries, reference documents
• Repeatable workflow definitions
• General-purpose scripts written in Shell, Python, Node, etc.

Category Two: Tool Adaptations (Must Be Handled Separately)

These items are tightly coupled to the mechanisms of a specific tool:

• Which entry-point file is auto-loaded at startup
• The directory from which skills are discovered and the naming structure they must follow
• Where configurations for external services (e.g., MCP-style protocols) are stored
• The event model and output protocol used by hooks
• The permission model adopted for command execution

Core principle: The first category should be maintained as a single shared source; only the second category should be adapted per tool. Without this initial separation, the most intuitive approach—copying the entire directory—may seem fastest at the outset, but it becomes the most expensive approach to maintain in the long run.

Overall Architecture of the Solution

The final design can be summarized in a single sentence: Project assets exist in only one place, and each tool is connected through a very thin adapter layer.

The directory structure looks like this:

project-root/
├── AGENTS.md            # Entry for Tool B: thin launcher
├── CLAUDE.md            # Entry for Tool A: thin launcher
├── .shared/             # The only directory for project assets (single source)
│   ├── rules/           # Project specifications and architectural conventions
│   ├── memory/          # Long-term memory, tasks, pitfall records
│   ├── knowledge/       # Business knowledge base
│   ├── workflows/       # Workflow definitions
│   └── scripts/         # General-purpose scripts
├── .adapter-a/          # Adaptations for Tool A: skill discovery, hook configuration
└── .adapter-b/          # Adaptations for Tool B: skill discovery, configuration items

All valuable rules, memory, knowledge, and scripts converge into .shared/. The entry-point files on either side do only one thing: they tell their respective assistants, “Go read the real project context here.”

Implementation Steps

Step 1: Establish a Thin Launcher as the Entry Point for Tool B

Most mature AI coding assistants support project-level instruction files. The tool automatically reads this file before initiating a task, and typically follows a chain-based lookup rule from the Git root directory down to the current working directory—the closer the file is to the current directory, the higher its priority. Also, the instruction chain typically has default size limits, so the entry-point file is not suitable for holding a full protocol.

The correct approach is to make the Tool B entry point an extremely thin “router file” with only two essential sections:

# Project Startup Guide
All long-term assets for this project are centrally stored in the `.shared/` directory. Before starting any task, you must read the following files first:
1. Project specifications and architectural conventions under `.shared/rules/`;
2. Current task and progress in `.shared/memory/task.md`;
3. Historical pitfall records in `.shared/memory/lessons.md`.
Do not change the semantics of the above files during a session. If modifications are needed, seek user confirmation first.

This way, the Tool B assistant is correctly directed to the single-source assets on every startup, and the entry-point file itself will never grow out of control.

Step 2: Point the Tool A Entry Point to the Same Assets

Similarly, slim down Tool A’s original oversized entry file, keeping only a small amount of Tool-A-specific instructions (such as permission preferences), and convert the rest into references pointing to .shared/. Once this transformation is complete, both tools read physically the same files, and rule drift is eliminated at the mechanism level.

Step 3: Migrate Memory and Task Files

Long-term memory is the part most prone to divergence. Three recommendations:

1. Split files by granularity: Store content in separate files categorized as “task status / architectural decisions / pitfall records,” rather than one monolithic file. This allows each tool to reference exactly what it needs.
2. Establish an update protocol: Make it explicit in the rules that “whenever either side generates new experience, it must be written back to .shared/memory/, rather than remaining in a session.” This turns memory accumulation into a procedure both tools follow.
3. Put memory under version control: Track memory files in Git. Every modification made by either tool produces a diff, making changes traceable, reversible, and synchronizable.

Step 4: Handle Differences in Skills and Hooks

Skill files are typically Markdown with metadata. The content itself can be shared, but the discovery path and loading mechanism vary from tool to tool. The approach: store skill content in .shared/, and place only references or registration configurations in each tool’s adapter directory:

<!-- Register a skill reference under .adapter-b/ -->
Name: db-review
Source: .shared/knowledge/db-review.md

Hooks differ more significantly—event models and output protocols are often not interoperable. Do not force unification here. A pragmatic approach: extract the business logic that hooks need to execute into general-purpose scripts under .shared/scripts/ (e.g., lint checks, pre-commit validations). Each tool’s hook then becomes a thin “shell” that invokes the same script. In this way, the hook logic always remains single-sourced.

Step 5: Handle Permission and Workflow Differences

The permission model is purely a tool-layer concern. It neither has to be nor can it be shared; simply configure it per tool within each adapter directory. Workflows are the opposite: a workflow is essentially “what to do and in what order,” independent of which tool executes it. Therefore, workflows belong in .shared/workflows/, referenced by both tools through their entry-point files.

Post-Migration Verification Checklist

• Both entry-point files are thin launchers and contain no full-length protocols
• A project-wide search finds no duplicate copies of rules or memory
• After updating rules on one side, the other side can read the latest version without any additional action
• General-purpose scripts exist in only one place, and both tools’ hooks are thin wrappers
• Memory files are under version control

Conclusion

The thinking behind this approach can be generalized to any scenario where multiple tools share a single project context: assets belong to assets; adaptations belong to adaptations. Tools may come and go, and accounts may face unexpected issues, but the rules, memory, and knowledge accumulated in a project are long-term assets. They rightly exist independently of any single tool. As long as you hold the line on “single source plus thin adaptation,” no matter how many AI coding assistants you integrate in the future, the project context will always have exactly one version of the truth.