Potential Improvements

[MauScheff]

Hi @rlmark

I came across these repo on how to best use LLMs with Unison code, and because this is a direction I care about, I'm happy to help in trying to make this better.

It seems like all instructions, language ref, testing (prompts) are already well written. A few things that came up (I'm using codex-cli and it may be slightly different than other agents).

• codex-cli uses AGENTS.md: maybe worth documenting how these plays with other files? eg. should we say in AGENTS.md to use those files when needed, or merge those files into AGENTS.md (sent across every request).

• another useful tip, could be to enable web search in codex-cli, and then include the additional instruction to lookup up to date documentation in Unison Lang Docs when things aren't working (I noticed it's trying to use the MCP to type check).

• Worth exploring what's the ideal dev flow for this (I'm guessing you already did this) and explicitly suggesting to do things "this way" up front in documentation (or a video).

• also may be worth considering including an "Agent resources" in website with a link to llms.txt or similar so that when crawled again, it picks up the latest docs. For example, notice how Cloudflare does it on this page. Same for Unison Cloud / Share.

Hope this helps,
Maurice

[rlmark]

Thank you so much @MauScheff! This is an area we definitely need user feedback on. It's a quickly moving domain!

One of the things I'm hoping to do in a subsequent doc / video is to show how these files might be used or added as context during an actual Unison coding session. The challenge has been that while the MCP protocol itself has been defined, each client (IDE) seems to have its own conventions around loading context, exposing tools in the interface, and invoking the MCP server. I'm glad to hear about the Agents.md file; it seems like it might be a step towards a common interface for providing instruction sets! I'll see if I can work that in as a file.

I'm thinking that this llm repo might need a per-AI tool directory structure, with separate folders for configuration or prompt examples to load as context based on the tool's conventions. (VS code expects instructions in one place, Zed, another, etc). That way, folks who similarly use Codex CLI can ignore what doesn't suit their workspace setup.

I'll look into if we can expose an "Agent resources" file in the website; there are some interesting quirks about how the website content is turned into html, but maybe there are quick wins to be found there.

Thank you again!

[MauScheff]

That sounds like a good idea: to do a per-AI tool structure, we also know that different models respond differently to the same prompt, so each AI-tool (often with a default model) may diverge into its own conventions and best practices for best results.

I think it's more the plugins than the IDE's for example, I use codex across Zed, terminal, and VSCode and it uses the same configurations. Whereas Claude code has a different convention on how context is fed.

And yes, I remember that some MCPs where for example not yet compatible with codex-cli or other less known agents, this indicates what you suggest that the MCP protocol is not implemented same across clients, similar to browsers rendering html slightly differently.

Two things come to mind here:

1. Ideally, rather than relying on MCP or context injecting, LLMs understand and incorporate the latest Unison understanding in their latent space; but this is like SEO, it's hard to tell when the next crawl will happen, and what it pick up, so it's best to "do your best and let it go". I think the llms.txt (Agent resources) can help in this direction, but idk what else can help here. I'm not even sure that's the end goal of llms.txt, I think it's actually made for when agents for some reason decide to check the website and navigate and they have an easier time navigating raw markdown rather than html.

2. It's best to avoid the current approach of including all these instructions in the context, while it does work, it's suboptimal, and leads to context slop. Ideally, Agents.md or equivalent, is as short as possible but not shorter, indicating things like how to test, how things are structured, coding style, etc. Including the entire language reference across each request is relatively expensive in number of tokens, and context slop, we do have to do this now though, because the language is very new and the crawlers haven't really picked it up. Some other things like "how to code Unison" by interacting with codebase do make sense to include in Agents.md (context). The other alternative, that I see that could work, is offsetting as much "context" as possible to the MCP, eg. not just interacting with codebase, but also providing language reference documentation (eg. maybe equivalent to searching on website?). For example, consider how DaisyUI seems to be doing this well with their MCP, and even using it as a revenue stream.

For now, I think the best quick wins are what you suggest, of providing coding agent specific instructions and docs of best practices.

:)

[rlmark]

Hi @MauScheff, I'm going to be testing this AGENTS.md file in my VS Code setup. Surfacing in case it helps your CodexCLI workflow use the UCM MCP. Please let me know if you see any significant anti-patterns.

[MauScheff]

Hi @rlmark today I merged all text files you had before (including language reference into an AGENTS.md) which is suboptimal (and your approach of just mentioning the files is better in terms of context management : when LLMs already know the language though). I'm using GPT-5.2 and it's working well, much better than before (without these files), even when using a very long AGENTS.md (as a temporary hack until LLMs learn Unison), I'm tempted to try your new structure, but it's already kind of working this way (although it may be more expensive), I also added a few things at the top, like how / where to search for documentation. I'm sharing what I added for reference, and I will try your approach (which is the "right" one, technically, and what I'm suggesting in my previous messages actually) some other time when I find the time.

# Rules

IMPORTANT: Always refer to the Unison language guide below.

## Project architecture notes (my-project)

- ...
- ...
- ...

To assist me with writing Unison code, you'll operate in one of these modes:
* The DISCOVERY mode is used when searching for libraries on Unison Share that may be helpful for a task.
...

#### If you make mistakes

If you are having trouble, work in smaller pieces:

a) Don't write a bunch of code, then try to get it to typecheck. Write and typecheck a function at a time. 
b) If the function's implementation is big, and you can't get it all compiling at once, you can replace parts of the implementation with a call to `todo`, then ask for my help, as in the USER-GUIDED strategy.
c) NEVER write more code if the code you've just written doesn't typecheck.

...

### Looking up documentaion

When things aren't working, or you aren't sure how to to somethin in Unison 1.0.0, prefer looking up official up-to-date documentation over repetitive trial-and-error patchwork.

Official sources:
- Unison Lang Docs (Main): https://www.unison-lang.org/docs/
- Unison Lang Language Fundamentals: https://www.unison-lang.org/docs/#language-fundamentals
- Unison Lang Language Reference: https://www.unison-lang.org/docs/#language-reference
- Unison Codebase Management: https://www.unison-lang.org/docs/#unison-codebase-management
- Unison Cloud Docs (Main): https://www.unison.cloud/docs/core-concepts/
- Unison Cloud Schema Modeling: https://www.unison.cloud/docs/tutorials/schema-modeling/
- Unison Cloud Local Development: https://www.unison.cloud/docs/local-development/
- Unison Cloud Local Development FAQ: https://www.unison.cloud/docs/local-development-faqs/
- Unison Cloud Durable Storage FAQ: https://www.unison.cloud/docs/general-storage-faqs/
- Unison Cloud Schema Migration FAQ: https://www.unison.cloud/docs/storage-schema-management/
- Unison Cloud Storage Types Cheat Sheet: https://www.unison.cloud/docs/storage-solutions/
- Unison Share Package repository: https://share.unison-lang.org/
- Example package documentation (Log): https://share.unison-lang.org/@unison/cloud/code/main/latest/types/Log
- Example package documentation (Cloud): https://share.unison-lang.org/@unison/cloud/
- Example package documentation (HTTP): https://share.unison-lang.org/@unison/http

Basically concatenated:
instructions, then 
---
then, testing, then
---
then language reference.