Agentlink guide

CLAUDE.md and AGENTS.md: symlink or wrapper?

Link the files only when their content should remain identical. Keep a real CLAUDE.md wrapper when Claude Code needs extra instructions, a deliberate import, or a different scope.

By Sam RogersPublished September 1, 2026Agentlink v0.5.0

Use a symlink for identical guidance

If both tools should receive the same project rules, a CLAUDE.md symlink to AGENTS.md is the simplest topology. There is one source to edit and review. The link is transparent in the repository, and Agentlink can repair it if it becomes broken or points somewhere else.

# .agentlink.yaml
source: AGENTS.md
links:
  - CLAUDE.md

agentlink sync --dry-run
agentlink sync

Use a real wrapper for Claude-specific guidance

Claude Code supports importing another file from a real CLAUDE.md. This is the better fit when most instructions are shared but Claude needs an additional planning rule, directory note, or workflow convention. Leave CLAUDE.md out of Agentlink’s links list so it remains an ordinary committed file:

# CLAUDE.md
@AGENTS.md

## Claude-specific guidance
Use plan mode before changing files under src/billing/.

Agentlink does not generate or edit wrappers. The wrapper’s import expansion, precedence, and nested discovery are features of Claude Code, so verify them against the tool version you actually use.

Decision table

Requirement	Recommended topology
Every instruction must be byte-identical	Symlink `CLAUDE.md` to the source.
Claude needs additional guidance	Real `CLAUDE.md` importing `@AGENTS.md`.
Claude guidance intentionally differs	Real independent `CLAUDE.md`; do not link it.
You are unsure which integration is preferred	Run `agentlink detect --generate --prefer-native` and inspect the recommendation.

Avoid accidental replacement

If a real CLAUDE.md already exists, a normal sync reports the conflict rather than overwriting it. Review the file first. Use --backup only when converting that regular file into an alias is intentional, and keep the backup outside your final committed topology. Agentlink refuses to recursively replace a directory or special file.

Monorepos add another scope decision

A root wrapper does not prove that every nested package uses the same precedence model. For a large repository, document the root defaults first, add nested instruction files only where the local work truly differs, and confirm that each consuming tool discovers those nested files. The monorepo instruction-file guide explains Agentlink’s fail-closed behavior.