docs: add CONTRIBUTING.md and rewrite AGENTS.md#3
Conversation
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
CONTRIBUTING.md covers code organization, module system conventions, TypeScript config, scripts, dev setup, and release process. AGENTS.md is rewritten to focus on behavioral contracts, operational grounding, and known failure surfaces rather than describing the project. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Ethan-Arrowood
changed the title
Ethan-Arrowood
changed the title
| - Do not edit files in `dist/`; it is compiled output and gitignored. | ||
|
|
||
| ## Code Style | ||
| - Use ESM and TypeScript |
There was a problem hiding this comment.
I'm curious, have you seen examples of AI not picking up on the code style? Or noticing the erasableSyntaxOnly in the tsconfig.json?
I have been thinking that the main value of AGENTS.md:
- Giving information that isn't accessible in the context.
- Accelerating the comprehension of the code base without having to spend a bunch of tokens reading a lot of source code on every new task.
But definitely curious where we find other values.
There was a problem hiding this comment.
I generally agree with that. Here is the definition I've come up with for AGENTS.md:
The
AGENTS.mdis a minimal, agent-specific document complementary to theREADME.mdandCONTRIBUTING.md. It answers what does an agent need to know that it cannot reliably infer from existing documentation?. Furthermore, it does not replace or duplicate existing documentation.
We can reasonably assume an agent can read the tsconfig and discern facts from it, but that then requires it reading the tsconfig and interpreting those rules every new session. By putting the important stuff in the AGENTS.md, it can skip reading tsconfig unless it has to (to say debug a TS issue).
I think its very arbitrary what we do or don't include in an agents.md file. The important bits is that it should be factual and succinct. I think if we find the agent constantly looking for additional information about the project when its tasked with doing something, we may want to add that information to the agents.md document.
There was a problem hiding this comment.
Btw I incorporated some of your thinking in some general guidelines for this doc: HarperFast/code-guidelines#9 want to iterate on it there?
#3 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2 participants
Summary
CONTRIBUTING.mdwith code organization, module system conventions (ESM/.tsimports,erasableSyntaxOnly), tsconfig explanation, scripts, dev setup, and release processAGENTS.mdto focus on three things only: behavioral contracts (what's safe to run autonomously), operational grounding (things agents need stated explicitly), and failure surface (footguns and constraints)🤖 Generated with Claude Code