Single Documentation File for agents #606
Description
When building applications using LLMs such as Claude Code, it is often helpful to point the agent to a single markdown AGENTS.md, or a CLAUDE.md file that describes the key details of the library relevant to the task.
It would be helpful to have such a markdown file available for quickly referrring agents to to allow them to quick start building applications using effectful - we could generate it directly from the docstrings/notebooks to avoid it going stale and host it on the documentation website, and give instructions on the readme telling people to point agents at this file.
Often when I'm trying to use effectful in other projects, I find myself spending some amount of time crafting the prompt to tell the agent how to use effectful, and otherwise it spends time digging into the effectful source inside the venv directory to work out what to do.
I ran an experiment on OpenAI and Anthropic asking:
use effectful (https://github.com/BasisResearch/effectful) and write some code using its llm functionality to do a multi-agentic workflow of a coder agent, an architect agent and a reviewer agent that work together to build a small ed-like text editor
Both Opus,Sonnet, and GPT-5.2 were able to produce working code after reading through several web pages, but the older models/haiku/gpt-5.0-instant, failed to produce working code with subtle issues. Having a single markdown quickstart could make the library substantially easier to use.