From CLAUDE.md to FUTURE.md: Porting Your Memory System to FutureX

Vibe coding has shifted the center of gravity in software projects from static docs to machine-readable memory files. Teams on Claude Code accumulate weeks of hard-won conventions in a CLAUDE.md file: build commands, style rules, security constraints, and architectural decisions written in plain Markdown. When you migrate to FIM, that knowledge does not need to be rebuilt. FutureX, the AI coding agent in FIM, uses the same file-hierarchy memory system, and the porting path is shorter than most teams expect. This guide walks through the mapping from CLAUDE.md to FUTURE.md, including global rules, hooks, and subagents, so you can move without leaving your vibe coding guardrails behind.

The CLAUDE.md pattern and why it works#

The CLAUDE.md convention is simple: a Markdown file at the project root that the AI coding agent reads before any task. It captures context that would otherwise be re-prompted every session: how to run the test suite, which linter is authoritative, what the directory layout means, and what the team has agreed never to do. Because it is plain text, it is diffable, reviewable, and versioned like any other source file.

The strength of the pattern is its hierarchy. A project-level CLAUDE.md holds the rules that apply everywhere in the repository. Nested CLAUDE.md files inside packages or services narrow the scope so that a backend service can enforce its own invariants without polluting the root file. Global memory, stored at ~/.claude/CLAUDE.md, applies to every project the user opens. The net effect is a cascading set of instructions where specificity wins: deeper files override broader ones, and everything is discoverable.

The weakness is tool coupling. The merge order and the hook system are tied to one platform. The rules themselves, though, are mostly portable: prose, lists, and commands, not proprietary APIs. That is exactly what makes a migration to FIM tractable.

Source: justinmckelvey.com

The FIM file hierarchy: mapping memory to FutureX#

FIM mirrors the pattern with the FutureX memory file: FUTURE.md. FutureX reads FUTURE.md at the project root on every session start, alongside configuration in the .future/ directory. The merge order is the same cascade you know from Claude Code, with project-level rules taking precedence over user-level rules, and nested FUTURE.md files taking precedence over the root file.

Project-level: FUTURE.md#

The root FUTURE.md replaces CLAUDE.md one-for-one. Same location, same Markdown format, same purpose. The sections you kept in CLAUDE.md: Project Overview, Commands, Style Notes, Testing, Architecture, and the Do Not Do list. They carry over with headings renamed only if you want to. FutureX does not require a specific schema; it treats the document as instructions.

User-level and global rules#

Global CLAUDE.md maps to ~/.future/FUTURE.md. Anything you configured once so that every project inherits it, whether that is your commit message style, your preference for type hints, or your standard security checklist, belongs there. FIM also supports a global rules file that can be referenced from any project, which is useful for org-wide standards that should not live in every repository.

Team-level memory#

Teams migrating from Claude Code often realize the global file was doing double duty: personal preferences and team standards in one place. FIM adds a team-level memory file that you can commit to a shared repository and distribute, so the FutureX memory file for a team is versioned and reviewed like code. This is the cleanest way to keep vibe coding guardrails consistent across a group of contributors after the move.

Source: kdnuggets.com

From CLAUDE.md to FUTURE.md: porting the rules#

The mechanical port is the easy part. Most CLAUDE.md files are plain prose, which FutureX reads without modification. The work is in the parts that were implicit in Claude Code and explicit in FIM.

Style and conventions blocks#

If your CLAUDE.md said to prefer named arguments in Python or that components live in src/components, move that text verbatim into FUTURE.md. FutureX weighs the same kinds of statements. For maximum consistency, keep the imperative tone: run the formatter before committing rather than noting that the project usually uses the formatter. Command-like instructions transfer reliably.

Commands and verification#

The block everyone relies on: how to install, test, lint, and build. It ports directly into a Commands section in FUTURE.md. One subtlety: Claude Code users often invoke tooling through the agent's own slash commands. In FIM, the equivalent is a scripts section that documents the exact shell commands FutureX should run. If your CLAUDE.md referenced a Makefile, keep that reference; FutureX will call make just as you did.

Negations and guardrails#

This is where vibe coding guardrails actually live. Never run migrations in production, do not modify package-lock.json by hand, always add a changelog entry: these constraints transfer verbatim. FIM treats explicit prohibitions in FUTURE.md as hard constraints during planning and execution, so keeping the language of your original rules preserves the safety behavior you built up over time.

Hooks and subagents: turning rules into enforced behavior#

A memory file is passive documentation until something checks that the agent followed it. In Claude Code, hooks fire on lifecycle events and subagents specialize the workflow. FIM has direct equivalents, and this is the part of the migration where teams gain the most.

Lifecycle hooks#

The .future/hooks/ directory holds executable hooks that fire at defined points in the agent loop: before a tool call, after a file edit, or before the agent finishes. Your Claude Code hooks were probably shell scripts checking for tabs, running a formatter, or blocking writes to protected paths. Those scripts are portable; move them into .future/hooks/ and adjust any path references from .claude to .future. FutureX also runs a pre-session hook that can verify FUTURE.md is present and warn when a contributor has not set up global rules.

Subagents as specialized reviewers#

Claude Code subagents, defined as Markdown files with their own prompts, have a direct counterpart in FIM: subagents in .future/agents/. If your workflow had a security-reviewer agent and a docs-updater agent, recreate them as instruction files in that directory, then reference them from the root FUTURE.md when you need their checks to run. Because the format is Markdown prose, converting your existing subagent definitions is mostly a rename plus a path update.

Source: serenitiesai.com

The migration playbook#

Here is the concrete sequence for moving a working project from Claude Code to FIM without losing your guardrails.

1. Audit the current state. List every CLAUDE.md in the repository, plus the global file in ~/.claude/CLAUDE.md and any hook scripts under .claude/hooks/. Note which rules are project-specific, which are personal, and which are team-wide.
2. Create the FUTURE.md skeleton at the project root. Copy the content of the root CLAUDE.md verbatim into FUTURE.md. Keep the headings; FutureX does not care whether the naming matches the original tool.
3. Split honestly. If the global CLAUDE.md mixed personal preferences with team policy, move team-wide rules into a team-level FUTURE.md and leave personal rules in ~/.future/FUTURE.md.
4. Handle nested files. Each nested CLAUDE.md becomes a nested FUTURE.md in the same directory. The cascade behavior in FIM matches Claude Code, so deeper files continue to override the root.
5. Port hooks and subagents. Copy scripts into .future/hooks/, update any paths, and convert subagent prompts to .future/agents/.
6. Validate with a smoke test. Open a session, ask FutureX to summarize the rules in FUTURE.md, then run a typical task and verify that the guardrails you care about, such as formatter enforcement, protected paths, and mandatory tests, actually trigger.
7. Archive the originals. Keep the CLAUDE.md files in a branch or a docs archive for a release or two, then delete them. The goal is a single source of truth: the FutureX memory file. This gives you a complete AI coding agent setup that is auditable and versioned.

Source: justinmckelvey.com

Guardrails that survive the move#

Teams hesitate to migrate from Claude Code because the memory system feels proprietary. In practice, the format, which is Markdown prose, command lists, and prohibitions, is the portable asset. The CLAUDE.md alternative that FIM provides exists precisely so the same hierarchy can be expressed in its own terms. What changes is the execution layer: hooks become enforceable rather than advisory, and subagents make the rules apply consistently. The guardrails themselves, the reason the original file existed at all, are text, and text moves.

A few things to watch. Any CLAUDE.md instruction that referenced the tool's own UI commands will need rewriting as shell commands. Hook scripts with the string .claude in their paths need a search-and-replace. And anything that relied on an implicit environment should be spelled out explicitly in FUTURE.md, because the assumptions are different. Handle those three, and the migration is mechanical.

Conclusion#

The file-hierarchy memory system that made CLAUDE.md indispensable does not have to be left behind. In FIM, the FutureX memory file FUTURE.md, global rules in ~/.future/FUTURE.md, and the team-level file replicate the cascade with the same plain-Markdown ergonomics. Hooks and subagents in the .future/ directory take the guardrails you already wrote and turn them from suggestions into enforced behavior. Migrating from Claude Code to FIM is a file move, not a rewrite, and your vibe coding guardrails arrive intact.