161–170 of 398 posts
Markdown is certainly easy for humans to write, but as OpenAI pointed out last week, wouldn’t an XML-based format be easier for LLMs to parse and understand?
> but as OpenAI pointed out last week What are you referring to here?
From OpeAI's last week document for coding with gpt5.
> #3. Use XML-like syntax to help structure instructions
Earlier quoted context omitted.
It's so it doesn't clash with any project that actually has a functional `agents/` directory
Another reason to use a src/ directory for the actual source code.
I've gotten used to it, obviously - as someone with a career in IT for 20 years - but /etc & co. annoy me to no end. I know it will never change, I know why it won't change, I know GoboLinux will be just an interesting experiment, but it's still annoying.
How are you actually running this in practice with Claude Code? Do you just tell Claude to always read and follow AGENTS.md, or do you also use an MCP server to strictly control which commands (like pnpm test or pnpm lint) it can run? I’d love to hear what workflows or best practices have worked well for you in day-to-day use.
I have Claude Code maintain the files and reference links between them.
Earlier quoted context omitted.
.well-known/
This. Projects need to stop inventing their own root level files and directories. Stop polluting the root dir. I'm not a fan of the name "well-known", but at least it's a convention [1]. I think it'd be great if we took something like XDG [2] and made it common for repositories, build scripts, package managers, tooling configs, etc. [1] https://www.rfc-editor.org/rfc/rfc8615 [2] https://wiki.archlinux.org/title/XDG_B…
I guess I was one of the lucky 10000 :-)
Earlier quoted context omitted.
That won't save you if you want actual example.com/agents/foo routing and an (say, real estate) agents list at example.com/agents.
I feel bad that you're getting downvotes. The reason is that pretty much every modern web stack decouples the URL routing from the source code directory structure these days. It was a nice hack back in the day, but there are so many problems with it no one really does it any more. Some frameworks (Laravel, NextJS, etc) map from the directory structure to routes, but that's just a mapping rather than actually exposing…
A `.agents` directory (or routing pretending to be one) is nice because you are fairly unlikely to ever have user-facing `example.com/.agents` as a URL.
Earlier quoted context omitted.
Except not hidden. Why do people want to hide important files and directories? Particularly documentation? Tradition, I guess, but it's an antipattern that makes everything more opaque. Maybe robot_docs?
It is files that are meant to be read by software, not humans. From my point of view this seems like a prime candidate for a hidden directory?
Earlier quoted context omitted.
I like this idea. Do you have any middleware in your current setup that added the contents of this directory to the agent prompt?
I'd be interested in smarter ways of doing this, but currently I just use my CLAUDE.local.md to serve as the index.md in my example. It includes the 'specialist' .md files with their relative paths and descriptions, and tells Claude Code to use these when planning. I also have explicit `xnew`, `xplan`, `xcode` and `xcheck` commands in CLAUDE.md that reinforce this. For example, here's my `xnew`: ## Remember Shortcuts…
This should've been an .agents¹ with an index.md. For tiny, throwaway projects, a monolithic .md file is fine. A folder allows more complex projects to use "just enough hierarchy" to provide structure, with index.md as the entry point. Along with top-level universal guidance, it can include an organization guide (easily maintained with the help of LLMs). index.md ├── auth.md ├── performance.md ├── code_quality ├── da…
Earlier quoted context omitted.
Another reason to use a src/ directory for the actual source code.
Or accept the fact that we're in 2025 and not follow Unix conventions from when paper and printer ink were expensive and they were printing out listings, and just name the thing "source". I've gotten used to it, obviously - as someone with a career in IT for 20 years - but /etc & co. annoy me to no end. I know it will never change, I know why it won't change, I know GoboLinux will be just an interesting experiment, b…
I've -> I have
& -> and
co. -> company
won't -> will not
it's -> it is
Earlier quoted context omitted.
Another reason to use a src/ directory for the actual source code.
Or accept the fact that we're in 2025 and not follow Unix conventions from when paper and printer ink were expensive and they were printing out listings, and just name the thing "source". I've gotten used to it, obviously - as someone with a career in IT for 20 years - but /etc & co. annoy me to no end. I know it will never change, I know why it won't change, I know GoboLinux will be just an interesting experiment, b…