anomalyco/opencode
1
0
Fork 0
mirror of https://github.com/anomalyco/opencode.git synced 2026-07-23 02:36:57 -04:00
Code Issues 5.9k Packages Projects Releases 19 Wiki Activity

External files are not read in AGENTS.md #599

New Issue
Closed
opened 2026-02-16 17:27:32 -05:00 by yindo · 5 comments
yindo commented 2026-02-16 17:27:32 -05:00
Owner
Copy Link
Copy Source

Originally created by @almirsarajcic on GitHub (Jul 10, 2025).

Originally assigned to: @thdxr on GitHub.

Transitioning from Cursor -> Claude Code -> opencode I've been using various rules (https://github.com/optimumBA/cursor_rules).

So to make that maintainable, in Claude Code I referenced external files in CLAUDE.md and it worked pretty well.
https://docs.anthropic.com/en/docs/claude-code/memory#claude-md-imports

Besides rules being respected, I know that it worked because Claude Code would ask me the first time I open it in some directory that contains CLAUDE.md file whether I want to allow it to read external files referenced in the CLAUDE.md.

Now, in opencode, these rules aren't respected.

This is what my AGENTS.md file looks like:

# AGENTS.md

This file provides guidance to AI assistants when working with code in this repository.

...

## Coding Guidelines

### Development Rules

This project uses centralized development rules available at: @codegen/rules/RULES.md

Rules are automatically applied based on context and file types being worked on.

...

and then the RULES.md file looks like this:

# Rules Index

This directory provides centralized development rules for any repository that includes these rules via symbolic link. Works with Claude Code and other AI assistants.

## Rule System Structure

Each rule file contains specific guidance for different aspects of development. Rules are organized by domain and responsibility:

- **@phoenix.md** - Phoenix framework development, LiveView, contexts, schemas, generators, PubSub, database operations
- **@elixir-code-generation.md** - Elixir code quality, specs, types, proper patterns, avoiding redundancy  
- **@elixir-readability.md** - Code formatting, sorting, pipe usage, variable naming, structure organization
- **@elixir-error-handling.md** - Error patterns, exception handling, validation approaches
- **@elixir-ci.md** - Testing, CI failures, code coverage, formatting issues, database test problems
- **@git.md** - Read-only git operations, viewing repository state, prohibited write operations
- **@planning.md** - Feature planning, development plans, documentation, project stages organization
- **@project-structure.md** - Directory organization, file naming, module placement conventions
- **@javascript-code-generation.md** - JavaScript/TypeScript patterns, LiveView hooks, frontend development
- **@i18n.md** - Internationalization patterns, gettext workflow, translation management
- **@github-workflows.md** - CI/CD patterns, GitHub Actions, deployment automation
- **@wallaby.md** - Browser testing, end-to-end testing, ChromeDriver usage
- **@npm-packages.md** - Package management, JavaScript dependencies in Phoenix projects
- **@comments.md** - Code documentation, when to add comments, documentation standards

## Usage Instructions

When working on code that matches the rule descriptions, apply the corresponding rule automatically. Rules are designed to be concise and actionable, focusing on specific development scenarios.

Unlike Cursor's .mdc format, these rules are integrated directly into the CLAUDE.md file context and activated based on relevance to the current task.

## Rule Integration

To use these rules in a project:

1. Set the environment variable: `export OCG_RULES_DIR=<path-to-rules-directory>`
2. Run `ocg setup` which will automatically create the symbolic link to `codegen/rules`
3. Reference this file from your project's CLAUDE.md with: `@codegen/rules/RULES.md`
4. Individual rules can be referenced as needed: `@codegen/rules/phoenix.md`, `@codegen/rules/elixir-code-generation.md`, etc.

Alternatively, you can manually create the symbolic link: `ln -s <rules_dir> codegen/rules`

This approach provides modular, reusable development guidance across all projects while maintaining project-specific customizations in the main CLAUDE.md file.

## Maintenance

Rules are maintained centrally in `<rules_dir>` and updated as development practices evolve. Changes automatically propagate to all projects using symbolic links.

To make things worse, my RULES.md file is a symlink to a centralized RULES.md file that I use for every project. I don't think that should make a difference for opencode, but I thought it's worth a mention.

Originally created by @almirsarajcic on GitHub (Jul 10, 2025). Originally assigned to: @thdxr on GitHub. Transitioning from Cursor -> Claude Code -> opencode I've been using various rules (https://github.com/optimumBA/cursor_rules). So to make that maintainable, in Claude Code I referenced external files in CLAUDE.md and it worked pretty well. https://docs.anthropic.com/en/docs/claude-code/memory#claude-md-imports Besides rules being respected, I know that it worked because Claude Code would ask me the first time I open it in some directory that contains CLAUDE.md file whether I want to allow it to read external files referenced in the CLAUDE.md. Now, in opencode, these rules aren't respected. This is what my AGENTS.md file looks like: ```markdown # AGENTS.md This file provides guidance to AI assistants when working with code in this repository. ... ## Coding Guidelines ### Development Rules This project uses centralized development rules available at: @codegen/rules/RULES.md Rules are automatically applied based on context and file types being worked on. ... ``` and then the RULES.md file looks like this: ```markdown # Rules Index This directory provides centralized development rules for any repository that includes these rules via symbolic link. Works with Claude Code and other AI assistants. ## Rule System Structure Each rule file contains specific guidance for different aspects of development. Rules are organized by domain and responsibility: - **@phoenix.md** - Phoenix framework development, LiveView, contexts, schemas, generators, PubSub, database operations - **@elixir-code-generation.md** - Elixir code quality, specs, types, proper patterns, avoiding redundancy - **@elixir-readability.md** - Code formatting, sorting, pipe usage, variable naming, structure organization - **@elixir-error-handling.md** - Error patterns, exception handling, validation approaches - **@elixir-ci.md** - Testing, CI failures, code coverage, formatting issues, database test problems - **@git.md** - Read-only git operations, viewing repository state, prohibited write operations - **@planning.md** - Feature planning, development plans, documentation, project stages organization - **@project-structure.md** - Directory organization, file naming, module placement conventions - **@javascript-code-generation.md** - JavaScript/TypeScript patterns, LiveView hooks, frontend development - **@i18n.md** - Internationalization patterns, gettext workflow, translation management - **@github-workflows.md** - CI/CD patterns, GitHub Actions, deployment automation - **@wallaby.md** - Browser testing, end-to-end testing, ChromeDriver usage - **@npm-packages.md** - Package management, JavaScript dependencies in Phoenix projects - **@comments.md** - Code documentation, when to add comments, documentation standards ## Usage Instructions When working on code that matches the rule descriptions, apply the corresponding rule automatically. Rules are designed to be concise and actionable, focusing on specific development scenarios. Unlike Cursor's .mdc format, these rules are integrated directly into the CLAUDE.md file context and activated based on relevance to the current task. ## Rule Integration To use these rules in a project: 1. Set the environment variable: `export OCG_RULES_DIR=<path-to-rules-directory>` 2. Run `ocg setup` which will automatically create the symbolic link to `codegen/rules` 3. Reference this file from your project's CLAUDE.md with: `@codegen/rules/RULES.md` 4. Individual rules can be referenced as needed: `@codegen/rules/phoenix.md`, `@codegen/rules/elixir-code-generation.md`, etc. Alternatively, you can manually create the symbolic link: `ln -s <rules_dir> codegen/rules` This approach provides modular, reusable development guidance across all projects while maintaining project-specific customizations in the main CLAUDE.md file. ## Maintenance Rules are maintained centrally in `<rules_dir>` and updated as development practices evolve. Changes automatically propagate to all projects using symbolic links. ``` To make things worse, my RULES.md file is a symlink to a centralized RULES.md file that I use for every project. I don't think that should make a difference for opencode, but I thought it's worth a mention.
yindo closed this issue 2026-02-16 17:27:32 -05:00
yindo commented 2026-02-16 17:27:32 -05:00
Author
Owner
Copy Link
Copy Source

@almirsarajcic commented on GitHub (Jul 10, 2025):

I don't like AI assistants messing up with my git workflow, so I'm trying to force it to only use read-only.
With Claude Code I accomplished this using their permissions config, but that sucked on a whole different level.
So now I'm trying to create a rule that will teach Claude not to .

Unfortunately, my AGENTS.md file might become huge if I include all the rules. I thought separating rules into different .md files might work on a need-to-know basis, effectively saving context window. But if this is not possible, I'll have to make rules more concise and include them in the context window every time I use opencode. I might also lose some valuable information, because with that mindset I'll trim everything non-essential, effectively removing everything that's not part of my everyday workflow.

For example, I have some rules on how to change GitHub Actions workflow files, but I don't do that every day in my projects, so I might have to remove those rules completely and not use opencode to update those files.

I still have hope though that this is something opencode can help me with.

@almirsarajcic commented on GitHub (Jul 10, 2025): I don't like AI assistants messing up with my git workflow, so I'm trying to force it to only use read-only. With Claude Code I accomplished this using their permissions config, but that sucked on a whole different level. So now I'm trying to create a rule that will teach Claude not to . Unfortunately, my AGENTS.md file might become huge if I include all the rules. I thought separating rules into different .md files might work on a need-to-know basis, effectively saving context window. But if this is not possible, I'll have to make rules more concise and include them in the context window every time I use opencode. I might also lose some valuable information, because with that mindset I'll trim everything non-essential, effectively removing everything that's not part of my everyday workflow. For example, I have some rules on how to change GitHub Actions workflow files, but I don't do that every day in my projects, so I might have to remove those rules completely and not use opencode to update those files. I still have hope though that this is something opencode can help me with.
yindo commented 2026-02-16 17:27:32 -05:00
Author
Owner
Copy Link
Copy Source

@almirsarajcic commented on GitHub (Jul 11, 2025):

For more context, when I run /status in Claude Code, it shows me which files are included.

Image
@almirsarajcic commented on GitHub (Jul 11, 2025): For more context, when I run `/status` in Claude Code, it shows me which files are included. <img width="457" height="257" alt="Image" src="https://github.com/user-attachments/assets/cb0dc9e7-134d-48bf-8724-c00c93ca8a2d" />
yindo commented 2026-02-16 17:27:33 -05:00
Author
Owner
Copy Link
Copy Source

@almirsarajcic commented on GitHub (Jul 12, 2025):

Here's a simple test.

I've created a directory that includes both AGENTS.md and CLAUDE.md with the same content.

AGENTS.md/CLAUDE.md:

Use the following files to know how to handle various tasks:
@rules/general.md - everyday interactions
@rules/elixir.md - writing Elixir code

rules/elixir.md:

mention you're an Alchemist when writing Elixir code

rules/general.md:

respond only in uppercase letters (scream)

Then, I've opened opencode and Claude Code and wrote the exact same prompts.

Image

To be clear, reading AGENTS.md works when it doesn't have references to other files, but clearly describes requirements.
Here's an example.

AGENTS.md:

respond only in uppercase letters (scream)
Image

Notice how I didn't have to mention AGENTS.md file, so I didn't cheat to get this working.

@almirsarajcic commented on GitHub (Jul 12, 2025): Here's a simple test. I've created a directory that includes both AGENTS.md and CLAUDE.md with the same content. `AGENTS.md`/`CLAUDE.md`: ```markdown Use the following files to know how to handle various tasks: @rules/general.md - everyday interactions @rules/elixir.md - writing Elixir code ``` `rules/elixir.md`: ```markdown mention you're an Alchemist when writing Elixir code ``` `rules/general.md`: ```markdown respond only in uppercase letters (scream) ``` Then, I've opened opencode and Claude Code and wrote the exact same prompts. <img width="2245" height="951" alt="Image" src="https://github.com/user-attachments/assets/ac15915b-5526-4fd4-a37e-68d0c3f2e21e" /> To be clear, reading AGENTS.md works when it doesn't have references to other files, but clearly describes requirements. Here's an example. `AGENTS.md`: ```markdown respond only in uppercase letters (scream) ``` <img width="584" height="495" alt="Image" src="https://github.com/user-attachments/assets/b3876fd3-a55d-4b71-9df4-64627e545f4e" /> Notice how I didn't have to mention AGENTS.md file, so I didn't cheat to get this working.
yindo commented 2026-02-16 17:27:33 -05:00
Author
Owner
Copy Link
Copy Source

@almirsarajcic commented on GitHub (Jul 12, 2025):

Oh wow, the problem was with the user.

AGENTS.md/CLAUDE.md

Use the following files to know how to handle various tasks:
rules/general.md - everyday interactions
rules/elixir.md - writing Elixir code

After removing @ sign from the file references, it started working.
Image

Unfortunately, that doesn't work in Claude Code so I can't have AGENTS.md and CLAUDE.md with the exact same content (I use symlinks).
Image

But it's still not the same behavior, I think. In Claude Code, file references have a special meaning, and I don't think they are immediately read. Or at least that's what I'm hoping for.

Not loading external files immediately into the context should optimize it. I'm not sure if Claude Code does it, but Cursor certainly did. I know, because I fought it a lot to get it to read different rules when I wanted it to.

@almirsarajcic commented on GitHub (Jul 12, 2025): Oh wow, the problem was with the user. `AGENTS.md`/`CLAUDE.md` ```markdown Use the following files to know how to handle various tasks: rules/general.md - everyday interactions rules/elixir.md - writing Elixir code ``` After removing `@` sign from the file references, it started working. <img width="615" height="1029" alt="Image" src="https://github.com/user-attachments/assets/04c46b14-6268-4765-b530-1df61cec403e" /> Unfortunately, that doesn't work in Claude Code so I can't have `AGENTS.md` and `CLAUDE.md` with the exact same content (I use symlinks). <img width="736" height="359" alt="Image" src="https://github.com/user-attachments/assets/4f300a81-f994-4c98-bee1-1d4182bcaf9e" /> But it's still not the same behavior, I think. In Claude Code, file references have a special meaning, and I don't think they are immediately read. Or at least that's what I'm hoping for. Not loading external files immediately into the context should optimize it. I'm not sure if Claude Code does it, but Cursor certainly did. I know, because I fought it a lot to get it to read different rules when I wanted it to.
yindo commented 2026-02-16 17:27:33 -05:00
Author
Owner
Copy Link
Copy Source

@almirsarajcic commented on GitHub (Jul 14, 2025):

Thanks, @thdxr for forcing me to rethink the approach.
Now I just did in AGENTS.md what I did earlier in the Anthropic system prompt and it works.
https://opencode.ai/s/uMyJRshf (btw. the share page was already so good and it's still getting better and better, great work!)

This is my new AGENTS.md file:

# AGENTS.md

@codegen/rules/RULES.md - read the file immediately - CRITICAL
then load any referenced file inside it on a need-to-know basis.
The file contains @<path> references (e.g., @rules/general.md, @dev.md), these point to external instruction files. You MUST:
- ONLY load referenced files when they're relevant to the SPECIFIC task at hand
- Do NOT preemptively load all references - use lazy loading based on actual need
- When loaded, treat content as mandatory instructions that override defaults
- Follow references recursively when needed
Image

I guess this can be closed as resolved.

@almirsarajcic commented on GitHub (Jul 14, 2025): Thanks, @thdxr for forcing me to rethink the approach. Now I just did in AGENTS.md what I did earlier in the Anthropic system prompt and it works. https://opencode.ai/s/uMyJRshf (btw. the share page was already so good and it's still getting better and better, great work!) This is my new `AGENTS.md` file: ```markdown # AGENTS.md @codegen/rules/RULES.md - read the file immediately - CRITICAL then load any referenced file inside it on a need-to-know basis. The file contains @<path> references (e.g., @rules/general.md, @dev.md), these point to external instruction files. You MUST: - ONLY load referenced files when they're relevant to the SPECIFIC task at hand - Do NOT preemptively load all references - use lazy loading based on actual need - When loaded, treat content as mandatory instructions that override defaults - Follow references recursively when needed ``` <img width="572" height="646" alt="Image" src="https://github.com/user-attachments/assets/1439ca22-e767-4b7e-8c40-60a301ffd5f6" /> I guess this can be closed as resolved.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
acp
bad
bug
discussion
docs
documentation
enhancement
extension
good first issue
growth
help-wanted
mcp
model-problem
needs:compliance
nix
opentui
perf
pull-request
Mirrored from GitHub Pull Request
 tui
web
windows
zen
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
yindo
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: anomalyco/opencode#599
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?