Client-hosted context spec proposal#1
Conversation
|
Sourcegraph (Quinn Slack, CEO) gave feedback that they were going to review for implementation. They have invested in **/agent.md and /.agent/rules/.md but this would offer a way to standardize across platforms and doesn't prevent their users from using the documented approaches based on "agent" paths. |
|
|
||
| Properties individual context files MAY set: | ||
| - `description` - OPTIONAL - a description of the context file and where it would be most applicable. Default is empty string. A description MUST be set if the trigger is `agent`. | ||
| - `globs` - OPTIONAL - an array of glob patterns that define the files that the context file is applicable to. Default is `[*]` (all files). |
There was a problem hiding this comment.
IMO the name 'globs' isn't great. Something like 'appliesTo' would be more intuitive. Practically glob is the type of the value. Not a descriptive of purpose.
There was a problem hiding this comment.
Yeah I can definitely appreciate that. Even from a passing the file to an LLM perspective (though they typically wouldn't directly), this wouldn't be super clear to even an LLM. I think for backwards compatibility both should be supported.
There was a problem hiding this comment.
Agree on both points - appliesTo: <globs> seems like a better default, but supporting globs: so that things like cursor rules can be easily moved over may be nice.
edit: I am questioning how important backwards compatibility is when we could easily write a tool to convert Cursor rules/etc to .context format.
digitarald
left a comment
digitarald
left a comment
There was a problem hiding this comment.
Took a first pass, still need to dig deeper and provide specific suggestions.
| --- | ||
| description: "Format preferences for JavaScript files" | ||
| appliesTo: **/*.{js|ts}, webpackconfig.js | ||
| trigger: auto |
There was a problem hiding this comment.
Lets clarify if this is for models or humans.
In some of the latest MCP discussions the ideas was to have separate tool call instructions and human descriptions. description can still be used for tool calls if instructions is not present.
There was a problem hiding this comment.
I'm trying to think of an example of how a context file would need instructions vs a description. Do you have any? I think there's a fundamental difference around the need for a tool vs context file. What are your thoughts?
There was a problem hiding this comment.
This is how agent-trigger works, it uses the description as include-this-rule-for-this-task natural language instruction (similar to tool call descriptions).
There was a problem hiding this comment.
Yeah totally. I am just unsure when "instructions" would be used in a way for context files that looks different than "description". I see the value of instructions for tools, but not seeing it yet for context files. Including both feels like a trap for confusion unless we can differentiate when we would expect and end user to use it - that's what I was looking for in terms of an example.
There was a problem hiding this comment.
One area I could see having description vs instructions is when sharing context files.
I wrote this Zod 4 context file and ended up putting "human instructions" in the file itself, and users just have to remember to take that out when using it:
https://github.com/jahands/prompts/blob/main/zod/zod-v4.md
Would have loved to have a separate field for "human consumption" in this case.
When I add the rule to a repo, I add a description/instructions for LLMs:
There was a problem hiding this comment.
thanks for the example! That really helps solidify the need when mixing this in a context file
| --- | ||
|
|
||
| Keep the modules in alphabetical order but grouped by external import vs internal imports. | ||
|
|
There was a problem hiding this comment.
This list represents the organically grown modes in the current ecosystem, but now would be the time to rectify this into a well defined configuration. As a start auto and agent are not clearly differentiated terms.
There was a problem hiding this comment.
I agree. Let me think through some options there and we can adjust
There was a problem hiding this comment.
Do you have any ideas for this? I moved "auto" to "pattern" but I feel like the list does a sufficient job for these options currently now that "auto" (which never made much sense next to other options) was changed to "pattern"
There was a problem hiding this comment.
pattern makes a lot more sense to me! I like the current list
|
|
||
| AI systems MUST normalize all path separators for the client operating system and expand the home directory symbol (~) using standard OS conventions. | ||
|
|
||
| AI systems SHOULD avoid following symlinks by default to avoid unintentional context inclusion. |
There was a problem hiding this comment.
What if ~/.context is a symlink? Asking because I typically keep all of my config in a git repo in ~/.dotfiles and then symlink everything from there so that all my configs are tracked in git.
edit: realized this is a SHOULD and not a MUST, so some AI systems might allow symlinks?
| 2. mounted directory context configuration | ||
| 3. each ancestor context configuration that exists from leftmost directory to rightmost directory (most priority) | ||
| 4. recursively merge all context configuration files to generate the final configuration to apply | ||
| 1. `clientContext.includeFiles` - arrays should be appended to and deduplicated based on pattern |
There was a problem hiding this comment.
Are there any bounds for includeFiles globs? Is there anything preventing the AI system from traversing millions of files in node_modules for configuration? What happens if it finds millions of .context/ directories, each with a context-config.json? Should it limit how many configs it reads? Should it limit path depth?
Additionally, are there different rules for the global config?
For example, if ~/.context/context-config.json contains:
{
"clientContext": {
"includeFiles": ["**/.context/**"]
}
}does this mean that the AI system should traverse the entire filesystem in search for .context directories?
There was a problem hiding this comment.
There is already an existing specifics related to this
The client context path's directory MAY contain 0 context files or an unknown high number of files. AI Systems SHOULD limit the amount of context files allowed to be parsed and used. This specification does not set what the limit should be however AI Systems SHOULD inform users when AI System limits have been hit.
The client context path's directory MAY have subdirectories of unknown depth. AI Systems SHOULD limit the amount of subdirectory levels searched to a reasonable amount to avoid performance issues. This subdirectory limit MUST NOT be less than 3 to allow reasonable user categorization of context files.
let me know if it needs more elaboration.
| - **AI working directory**: the directory in which the AI system is preparing to or is actively working within. If an AI system supports having a mounted directory (like an IDE opening a coding folder), this mounted directory is the default AI working directory. If the AI system's mounted directory is `~/myproject/`, then the AI working directory is by default `~/myproject/`. If the AI system determines that it needs to add/edit a file within `nested/paths/`, the AI system's AI working directory changes to be `~/myproject/nested/paths/` during that task. The mounted directory stays the same but, depending on what the AI system's agentic decisions, the AI working directory MAY change during the course of the AI system's work. | ||
| - **Client context path**: the relative path string that is used to find context files and configurations. | ||
| - **Context configuration**: a configuration file that provides additional rules for searching and filtering context to an AI system while it is running within AI working directory. | ||
| - **Ancestor context**: When AI systems have a specific mounted directory (typically a project directory) and the AI working directory is at a nested directory, all context and configuration between these two directories is the ancestor context. For example, if the mounted directory is `~/myproject` and the AI working directory is `~/myproject/nested/paths/feature/` then context and context configuration that might exist within `feature`, `paths`, `nested`, `myproject` are the entirety of possible ancestor context. |
There was a problem hiding this comment.
Is ~/myproject/nested/paths/peer_folder/ considered as existing within paths?
There was a problem hiding this comment.
no that would be an upstream sibling/fork path. This ancestry is tracking direct lineage/parent folders
|
|
||
| ### Context configuration | ||
|
|
||
| The type signature of the configuration file is as follows: |
There was a problem hiding this comment.
Who is expected to create these configuration files?
There was a problem hiding this comment.
end users though I expect AI systems will keep an internal representation
|
|
||
| AI systems MUST filter context file types that they do not support themselves and SHOULD show a warning message where there are selected context files that are not supported by the AI system. | ||
|
|
||
| AI systems MUST validate the configuration file based on the above type signature and SHOULD show a warning message where there are configuration files that have invalid configuration. AI systems MUST NOT fail to start or work because of invalid configuration. |
There was a problem hiding this comment.
What should behavior be if there is invalid configuration? i.e something both included and excluded -- is it up to the discretion of the system
There was a problem hiding this comment.
there is already a section addressing this
Where `clientContext.includeFiles` and `clientContext.excludeFiles` overlap, the `excludeFiles` pattern takes precedence and any matching files MUST be excluded.
let me know if it needs more clarity
| 3. `clientContext.ignoreGlobalContext` - the last value wins | ||
| 4. `clientContext.ignoreAncestorContext` - the last value wins |
There was a problem hiding this comment.
Could this be confusing as a merge strategy?
There was a problem hiding this comment.
confusing for implementors or users? For users, I don't expect this to be used super often and thus I'd expect it to be low risk of confusion based on use. But in general, by "last value" we mean the most specific to the work being done so I think that makes things clear. What do you think?
|
@digitarald @janaka @1matthewli @jahands I've addressed all feedback, let me know what your thoughts on with this iteration |
|
what are you thoughts on how this spec resolves with the discussion in microsoft/vscode#249387 Fundamentally that is based on being of narrower scope. Is the thinking that it's covered by this spec's compatibility features? |
Yes the idea is bringing both vscode folks together along with other agents/IDEs to create a simple but flexible shared spec. At this point, I don't see anything that isn't possible to support with the layout of this spec (and if there is, let's sort out what those gaps may be). |
|
Cool, the |
6 participants
There are many inconsistencies across various AI systems regarding where context should live, how it should handle global or nested context, etc. This specification aims to establish alignment across AI systems that require sourcing and utilizing client context.
The specification has been derived from analyzing various AI systems and their local context-pulling capabilities. The initial design is a combination of the best ideas/implementations from those systems with layers I've added to provide the most flexibility for systems to adopt this spec with full backwards compatibility. Additionally, I've added concepts that should help end users and context providers create custom layers to provide flexibility in how they provide context.
Most AI systems are very close to being able to support this spec with minor change.
Going forward, this sets up an excellent foundation for establishing patterns for concepts like dependency-controlled context, improving context formats for more optimized context formats that allow improved data density.
FAQ:
why not "agent" oriented files?
why default to .context directory instead of something like a single context.md
do users have to move their context into a new directory for context to work?