You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maka.apache.org by "shaokeyibb (via GitHub)" <gi...@apache.org> on 2026/08/23 08:43:58 UTC
[I] bug(runtime): a CLAUDE.md symlinked to AGENTS.md is injected into the prompt twice [maka]
shaokeyibb opened a new issue, #3577:
URL: https://github.com/apache/maka/issues/3577
## What happened
A repository that follows the mainstream way of sharing one instruction file across agent CLIs gets that file injected into Maka's system prompt twice.
`readWorkspaceInstructions` reads every candidate name in a directory and never compares the results:
```ts
// packages/runtime/src/system-prompt/workspace-instructions.ts
export const WORKSPACE_INSTRUCTION_FILES = ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md'] as const;
for (const file of WORKSPACE_INSTRUCTION_FILES) {
const candidate = join(root, file);
const resolved = await realpath(candidate);
if (!isPathInside(root, resolved)) continue;
const raw = await readFile(resolved, 'utf8');
out.push({ file, scope, text: ..., truncated: ... });
}
```
`realpath` is used only for the containment check; the entry is still recorded under the original name, so a `CLAUDE.md` symlinked to `AGENTS.md` resolves to the same file, is read again, and is appended again.
Measured against a checkout with that symlink, by calling `buildWorkspaceInstructionsPromptFragment` on the repo root:
```
without symlink blocks = project/AGENTS.md
with symlink blocks = project/AGENTS.md, project/CLAUDE.md
```
Both copies count against `MAX_WORKSPACE_INSTRUCTIONS_PROMPT_CHARS` (14000). With a file near the 6000-character per-file cap, the duplicate consumes most of the workspace-instruction budget, and any genuinely different file in the same directory is what gets dropped.
This is not an exotic setup. Claude Code's documentation recommends exactly it:
> Claude Code reads `CLAUDE.md`, not `AGENTS.md`. […] A symlink also works if you don't need to add Claude-specific content: `ln -s AGENTS.md CLAUDE.md`
`apache/airflow` ships that symlink, as does `deepseek-ai/deepseek-harness`.
The `@AGENTS.md` import form that the same documentation recommends fails differently: Maka does not expand imports, so a one-line `CLAUDE.md` containing `@AGENTS.md` is injected as the literal text `@AGENTS.md`. Harmless in size, but it is an instruction that means nothing.
## How to reproduce
1. In any workspace with an `AGENTS.md`, add `ln -s AGENTS.md CLAUDE.md`.
2. Call `buildWorkspaceInstructionsPromptFragment(cwd)`.
3. The fragment contains two `<workspace-instructions>` blocks with identical bodies.
## Environment
- Maka commit: `729839ed8`
- Surface: any — the fragment is shared by Desktop, TUI and CLI
## Logs, screenshots, or additional context
### How other agents avoid this
Three distinct strategies, and Maka currently uses none of them:
| Agent | Files read | Conflict resolution |
|---|---|---|
| Claude Code | `CLAUDE.md` only | not possible |
| Codex CLI | `AGENTS.md` only | not possible |
| Gemini CLI | `GEMINI.md` only | not possible |
| opencode | `AGENTS.md`, `CLAUDE.md` | first match wins — "if you have both `AGENTS.md` and `CLAUDE.md`, only `AGENTS.md` is used" |
| Pi | 5 candidate names | first match wins |
| DeepSeek Harness | several | content-digest deduplication |
Pi's loader returns on the first existing candidate per directory (`packages/coding-agent/src/core/resource-loader.ts`), and carries a separate guard against a linked worktree applying the same context twice — the same class of problem.
### Suggested direction
DeepSeek Harness is the closest analogue: it reads several names *and* ships the `CLAUDE.md` symlink, and reconciles them by content rather than by path. From `packages/context/agent-instructions/src/files.ts`:
> Drop later candidates whose trimmed content duplicates an earlier sibling in the same directory. Different directories never collapse even when identical; within one directory the earliest candidate in discovery order is kept and its original bytes are rendered. **A candidate that symlinks a sibling resolves to the same content and collapses here like any byte-identical real file.**
Deduplicating on the trimmed content digest, scoped to one directory, looks like the right shape for Maka too:
- it catches the symlink *and* two byte-identical real files, which a `realpath` check would miss;
- it keeps different directories independent, so the global/project layering still works;
- it changes nothing for the common case of a single instruction file.
First-match-wins would also work and is simpler, but it silently discards a `CLAUDE.md` that genuinely differs from `AGENTS.md`, which is a supported thing to have. Deduplication only drops what is redundant.
_Investigated with AI assistance (Claude Code); Maka behaviour measured on the commit above, other agents' behaviour read from their published docs and source._
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For additional commands, e-mail: commits-help@maka.apache.org
Re: [I] bug(runtime): a CLAUDE.md symlinked to AGENTS.md is injected into the prompt twice [maka]
Posted by "Astro-Han (via GitHub)" <gi...@apache.org>.
Astro-Han closed issue #3577: bug(runtime): a CLAUDE.md symlinked to AGENTS.md is injected into the prompt twice
URL: https://github.com/apache/maka/issues/3577
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For additional commands, e-mail: commits-help@maka.apache.org
Re: [I] bug(runtime): a CLAUDE.md symlinked to AGENTS.md is injected into the prompt twice [maka]
Posted by "shaokeyibb (via GitHub)" <gi...@apache.org>.
shaokeyibb commented on issue #3577:
URL: https://github.com/apache/maka/issues/3577#issuecomment-5385123518
I'm working on this.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For additional commands, e-mail: commits-help@maka.apache.org