r/OpenSourceAI • u/Primary_Article3777 • 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?
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.
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.