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

[PR #922] [CLOSED] Enable external references in AGENTS.md #9744

New Issue
Closed
opened 2026-02-16 18:14:05 -05:00 by yindo · 0 comments
yindo commented 2026-02-16 18:14:05 -05:00
Owner
Copy Link
Copy Source

📋 Pull Request Information

Original PR: https://github.com/anomalyco/opencode/pull/922
Author: @almirsarajcic
Created: 7/12/2025
Status: ❌ Closed

Base: dev ← Head: agents-file-references

📝 Commits (1)

  • a9dd9f5 Enable external references in AGENTS.md

📊 Changes

1 file changed (+7 additions, -0 deletions)

View changed files

📝 packages/opencode/src/session/prompt/anthropic.txt (+7 -0)

📄 Description

Resolves #832.

Thought I'd need to learn TypeScript for this, but simple English suffices. 🤷

Experimented for a while with different system prompts, and this one was the most concise one that worked.

Screenshot 2025-07-12 at 16 34 49

Here are two examples:

A real-world example from one of my projects.

https://dev.opencode.ai/s/hmPNhxY6

AGENTS.md:

# AGENTS.md

@codegen/rules/RULES.md - read the file immediately - CRITICAL
then load any referenced file inside it on a need-to-know basis

codegen/rules/RULES.md:

# Rules Index

Say "HELLO" at the start of every message!

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** - GitHub workflows with 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

...

codegen/rules/github-workflows.md:

# GitHub Workflows

Use for GitHub workflow and CI/CD pipeline configuration and usage.

- Update workflows exclusively by editing `.github/github_workflows.ex` file.
- After changing file `.github/github_workflows.ex` make sure to run `mix github_workflows.generate` command so that files in the `.github/workflows` directory reflect those changes.
- Remove directory `.github/workflows` before running `mix github_workflows.generate` to ensure stale workflows are removed after changing workflows in the input file.
- Prettier does not share steps with Elixir jobs, so don't refactor it to call `elixir_job/2` function.
Screenshot 2025-07-12 at 16 25 37

https://dev.opencode.ai/s/hmPNhxY6

A simple one that I used to test this initially while working on this PR.

https://dev.opencode.ai/s/z1hfn6W1

AGENTS.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)
Screenshot 2025-07-12 at 16 28 36

With a more elaborate system prompt, I was able to have uppercase, but it's too much of the space in the context window wasted on just file references.

image

https://dev.opencode.ai/s/55t579g1

# AGENTS.md File References (CRITICAL)
IMPORTANT: AGENTS.md files use @ symbols to reference external instruction files. You MUST handle these references properly:

When you see lines like:
- @rules/general.md - everyday interactions
- @path/to/file.md - specific domain rules

You MUST:
1. IMMEDIATELY read these referenced files using the Read tool when the current task relates to their description
2. Treat the content of referenced files as if it were directly included in AGENTS.md
3. Follow @ references RECURSIVELY - if a referenced file contains more @ references, read those too (up to 5 levels deep)
4. Track which files you've loaded to avoid circular references

Example: If the user asks you to write Elixir code and AGENTS.md contains "@rules/elixir.md - writing Elixir code", you MUST read rules/elixir.md BEFORE writing any Elixir code. The rules in that file are MANDATORY to follow.

This is NOT optional - these referenced files contain critical instructions that you must follow for the project.

However, with that in anthropic.txt, the other example didn't work until I explicitly mentioned that wasn't the way we deal with GitHub workflows.

image

https://dev.opencode.ai/s/H80UKiOk

so in the end I think I should just write better rule files descriptions to make Claude load them when necessary.

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/anomalyco/opencode/pull/922 **Author:** [@almirsarajcic](https://github.com/almirsarajcic) **Created:** 7/12/2025 **Status:** ❌ Closed **Base:** `dev` ← **Head:** `agents-file-references` --- ### 📝 Commits (1) - [`a9dd9f5`](https://github.com/anomalyco/opencode/commit/a9dd9f53a65ec5d0687cf20ea89968d2f179b0e6) Enable external references in AGENTS.md ### 📊 Changes **1 file changed** (+7 additions, -0 deletions) <details> <summary>View changed files</summary> 📝 `packages/opencode/src/session/prompt/anthropic.txt` (+7 -0) </details> ### 📄 Description Resolves #832. Thought I'd need to learn TypeScript for this, but simple English suffices. 🤷 Experimented for a while with different system prompts, and this one was the most concise one that worked. <img width="600" height="417" alt="Screenshot 2025-07-12 at 16 34 49" src="https://github.com/user-attachments/assets/e36cbf6c-ae16-4759-80b0-abdd442cf9a3" /> Here are two examples: <details> <summary> A real-world example from one of my projects. https://dev.opencode.ai/s/hmPNhxY6 </summary> `AGENTS.md`: ```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 ``` `codegen/rules/RULES.md`: ```markdown # Rules Index Say "HELLO" at the start of every message! 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** - GitHub workflows with 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 ... ``` `codegen/rules/github-workflows.md`: ```markdown # GitHub Workflows Use for GitHub workflow and CI/CD pipeline configuration and usage. - Update workflows exclusively by editing `.github/github_workflows.ex` file. - After changing file `.github/github_workflows.ex` make sure to run `mix github_workflows.generate` command so that files in the `.github/workflows` directory reflect those changes. - Remove directory `.github/workflows` before running `mix github_workflows.generate` to ensure stale workflows are removed after changing workflows in the input file. - Prettier does not share steps with Elixir jobs, so don't refactor it to call `elixir_job/2` function. ``` <img width="574" height="183" alt="Screenshot 2025-07-12 at 16 25 37" src="https://github.com/user-attachments/assets/414b0129-26e4-426d-a914-9f92c3e3503d" /> https://dev.opencode.ai/s/hmPNhxY6 </details> <details> <summary> A simple one that I used to test this initially while working on this PR. https://dev.opencode.ai/s/z1hfn6W1 </summary> `AGENTS.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) ``` <img width="606" height="219" alt="Screenshot 2025-07-12 at 16 28 36" src="https://github.com/user-attachments/assets/b5b78301-a559-4c57-9443-ef6c8a4d18df" /> With a more elaborate system prompt, I was able to have uppercase, but it's too much of the space in the context window wasted on just file references. <img width="736" height="617" alt="image" src="https://github.com/user-attachments/assets/e79f5662-578f-4e7e-a3fe-14a91388b3cb" /> https://dev.opencode.ai/s/55t579g1 ```plaintext # AGENTS.md File References (CRITICAL) IMPORTANT: AGENTS.md files use @ symbols to reference external instruction files. You MUST handle these references properly: When you see lines like: - @rules/general.md - everyday interactions - @path/to/file.md - specific domain rules You MUST: 1. IMMEDIATELY read these referenced files using the Read tool when the current task relates to their description 2. Treat the content of referenced files as if it were directly included in AGENTS.md 3. Follow @ references RECURSIVELY - if a referenced file contains more @ references, read those too (up to 5 levels deep) 4. Track which files you've loaded to avoid circular references Example: If the user asks you to write Elixir code and AGENTS.md contains "@rules/elixir.md - writing Elixir code", you MUST read rules/elixir.md BEFORE writing any Elixir code. The rules in that file are MANDATORY to follow. This is NOT optional - these referenced files contain critical instructions that you must follow for the project. ``` However, with that in `anthropic.txt`, the other example didn't work until I explicitly mentioned that wasn't the way we deal with GitHub workflows. <img width="736" height="617" alt="image" src="https://github.com/user-attachments/assets/d742da98-0aea-4368-8601-11e76c827606" /> https://dev.opencode.ai/s/H80UKiOk so in the end I think I should just write better rule files descriptions to make Claude load them when necessary. </details> --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
yindo added the pull-request label 2026-02-16 18:14:05 -05:00
yindo closed this issue 2026-02-16 18:14:05 -05:00
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 pull-request
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#9744
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?