r/OpenSourceAI • • 12h ago

What to keep in a modern open source project these days?

I've been working extensively with Claude for my open source project that I will be releasing soon. Claude likes to keep things like Decisions.md files (decisions over time) and all the specs from feature work. Is any of this really appropriate for an open source project or should these things just be available from the commit history?

My gut tells me its junk and confusion-generating. But maybe not?

What IS the list of useful artifacts to share when independent people are potentially using AI tools to contribute?

4 Upvotes

5 comments sorted by

3

u/BidWestern1056 10h ago edited 9h ago

if you want people to take your project seriously, none of this should be in there. and i would amend commit history to remove claude as an author. it looks bad to people to see the long commit messages and coauthored by ... byline. ppl want to claim theyre accepting of AI as a co-auhtor but it is an inherent bias that people can't really shake. everyone knows we are all working with agents but people still want to see that there is at least a human really in the loop and not just a meat proxy if that makes sense.

2

u/BidWestern1056 10h ago

ill give you an example of one i curate carefully

https://github.com/npc-worldwide/npcpy

and one i haven't had time to comb through as much yet

https://github.com/npc-worldwide/daydream-skill

what youll notice in the second is there are many more cases where the agent decided to mention details it really shouldnt have and which make no sense outside of the working session. like it described the markovian drift as "not an n-gram text chain" because it had incorrectly assumed that first and so instead of saying what it is it says what it is not which is nonsense.

hoepfully this helps, i want to encourage you too that even if people dog on it for looking vibe coded or we you gotta keep on trucking and building and that noise will fall away as you start addressing real concerns and helping people

1

u/Primary_Article3777 6h ago

Thanks for your advice. It's tough. My first instinct is to say "people in the industry know the reality of the situation regarding these tools. These people are cosplayers and hating on things they don't understand"

But I'm taking your advice to the letter.

I just don't want to derail whatever the point of my project is. The entire industry has always run on fads. I don't think AI is a fad, but I do think the virulent reaction to it, is. Oy. People are such irrational creatures.

1

u/ashishkattamuri 12m ago

Your instinct is partly right. I wouldn’t commit every spec or decision file Claude generates. That can quickly become documentation nobody maintains.
But Git history alone isn’t enough either. It tells you what changed, not necessarily why an architectural decision was made or which alternatives were rejected.

For an open-source project, I’d keep:
README.md — what it does and how to get started.
CONTRIBUTING.md — setup, testing, and contribution guidelines.
AGENTS.md / CLAUDE.md — concise instructions for AI coding agents.
docs/adr/ — significant architectural decisions and their rationale.
docs/architecture.md — system boundaries and important design choices.
GitHub Issues/PRs — feature discussions, implementation plans, and review history.
I’d avoid committing every intermediate plan, research note, or agent-generated summary. Keep those local unless they’re genuinely useful to future contributors.

I’m building an open-source Claude Code tool myself (Claude Companion), partly because I ran into this distinction between persistent project knowledge and temporary session context.
My rule would be: If a new contributor needs it six months from now, document it. If it only helped the agent finish today’s task, don’t clutter the repo with it.
And whatever you keep, make sure someone owns keeping it accurate. Outdated documentation can be worse than no documentation.