Teach humans to contribute, not machines
I love contributing to open-source projects. There is this insanely good feeling that I get when my changes get merged into the main branch. Dopamine goes through the roof when I see the number of “projects I’ve contributed to” go up, and the shade of blue on my contribution graph get that little bit darker. I wish I could do this my whole life. Contributing to open source is not easy, though, especially to the projects one hasn’t worked with yet. Of course, the biggest hurdle is the programming language one might not know. Then, it’s finding the issue to tackle. But these are the hurdles one should come to expect. But you know what’s the hardest thing about contributing, once you’ve found a project and picked an issue to work on? It’s getting the damn thing to run. When it comes to the ways a project should be run (let alone, developed), one should cue xkcd #927 . And, the bigger the ecosystem, the worse it becomes. I can guarantee you that, if you pick any two libraries that are written in the same language, they will have different commands to build them. Which is fine – different projects have different goals and different maintainers (with different opinions) – but discovering those is often outright impossible. Blessed be your soul if you tell me I should just run in your README! Or, even better, if you have a CONTRIBUTING.md outlining everything I need to know – from prerequisites to coding style to pull request guidelines. But that’s not always the case. In the past, I had to do a lot of guesswork. Do some npm scripts have telling names? Maybe there’s a Justfile? In the end, I was either reading the CI workflow files, trying to understand what someone else’s computer executes to achieve the same goal as I, or I gave up and watched said CI server do it for me after I’ve submitted a PR blindly. But then, something changed. With each day, more and more people are writing good contributor guides! All very well-structured and full to the brim with commands, style guides, and tips and tricks. The catch in that whole thing? The file is named different. It’s no longer called CONTRIBUTING.md. It’s AGENTS.md. That prick Claude and his dorky lil’ friends! We, the humans, have been demanding good documentation and help with contributing for ages, and they come in and get it served right to them! It’s a crazy feeling of both deep sorrow and weird joy that I get when yet another thing that’s helpful for your “agents” shows up – because it could and frequently is very beneficial to us, humans. Don’t like the CSS and JS of the project’s website? The docs are arranged weirdly, and you find yourself clicking around too often? llms.txt to the rescue! You don’t know if the project want’s regular or conventional commits? Just look in the AGENTS.md! You need to do something with a PDF, but you don’t know how? Just look at how Claude would do it with its “skills”! Finally, the thing that motivated me to write this post. Andrew Nesbitt, an awesome fella of ecosyste.ms fame, has just announced . The idea, and it’s execution, is insane (in a good way): Just run the command, and you’ll get all information on a project you need! Build, lint, and test commands, code formatting, supported OSes; it’s basically the solution to the problem I’ve had in the first paragraphs! But wait – how should one use this tool? Add this to your […] agent instructions file: Before starting work on this project, run to understand the toolchain, test commands, linters, and project conventions. The agent will get back structured information […] so it doesn’t have to guess or ask you. I wonder where this phenomenon is coming from. I guess that we, the programmers, who have made it out job to command a soulless machine, can not get enough of it. As if we’re not thinking enough about human interaction, or at very least are not getting enough fun from it. Coding is fun; typing stuff and see computer act (mostly) the way you want is fun. And it’s very easy to forget about the other developers a become one with the project. The perfect Makefile. The flawless CI pipeline. The impeccable AGENTS.md. But please, wake up from that dream. As good as it might feel (you don’t have to tell me!), you should still realize that you’re not alone. That somewhere out there, separated from you by thousands of kilometres of underwater cables, electromagnetic waves, and copper wires, there is another human, just like you. And that human does not want to deduce the build flags from reading your goreleaser.yaml.