网页
综合
更新时间 2026-05-03 01:48:40
I always worried my READMEs disagreed with my own repos. So I built README Clew. - DEV Community
自动蜘蛛
dev.to
正文约 3523 字
Posted on May 3 • Edited on Oct 11 • AI-assisted
I write a lot of READMEs. I ship faster than I document. I work with AI agents that write code in seconds and READMEs in minutes, and somewhere between the first commit and the third refactor, the README I wrote on Tuesday stops matching the code I wrote on Friday.
The install command says npm start. The package.json defines start:prod. Anyone copying that command would have failed instantly. I'd never know.
This weekend, for the Replit 10 Year Buildathon, I built README Clew — a tool that audits your own GitHub repo for drift between what your README claims and what your code actually does.
Findings only. No rewrites. No grading. Nothing saved.
README Deployed Try it → Github Repo GitHub →
Paste a public GitHub repo URL. README Clew:
The five categories I check:
The four buckets, in display order:
(https://dev-to-uploads.s3.amazonaws.com/uploads/articles/jprc7a5ffhpjdr4h4w1f.png)
I shipped more than I planned to:
The badge is my favorite. Audit your own receipts, then embed your status in the receipt itself.
The findings stung in good ways.
On Memoria Clew (4th of 250 in the AI Vibe Coding hackathon, February): twenty undocumented items in my package.json — dependencies my code uses, scripts I'd added, env vars I'd never written down. One actual contradiction in the README too.
On petit-mot: 16 of 21 claims verified. All file references resolve. 5 unverifiable because the project has no package.json — deployment commands fall outside what static analysis can check.
On README Clew itself: zero contradictions, but seventeen things I'd shipped without documenting. The tool found drift in its own creator's documentation. That's the point.
The tool is intentionally narrow. Five deterministic verifiers run on actual code. One Claude API call extracts claims from your README. The system prompt instructs Claude to use only verbatim quotes from the README — not paraphrase, not invent. That's a prompt-level guardrail, not a post-processing validation step. Honest distinction worth making.
Every finding shows you the README quote and the code reference. Don't trust the verdict, trust the receipts. You can always click through and verify yourself.
Known limitations I'm honest about:
The transparency is the trust.
Hybrid architecture: deterministic where it matters, AI where it adds value. The AI's role is narrowly scoped to extraction and synthesis, never to the verification itself. Five verifiers, one orchestrator, one extraction call, one optional summarization call. That's the whole pipeline.
Building anything that takes user input and calls external APIs needs to take the threat model seriously, even at hackathon scale.
Not production-hardened (no auth, no audit log, intentional). Solid for a public stateless tool.
🔗 readme-clew--earlgreyhot.replit.app 📦 github.com/earlgreyhot1701D/readme-clew 🎂 Built for the Replit 10 Year Buildathon
For further README inspo check out https://dev.to/georgekobaidze/15-essential-sections-every-readme-needs-give-your-project-what-it-deserves-fie
Run it on one of your own repos. Tell me what it finds.
Apache 2.0 licensed.
AI assisted. Human approved. Powered by NLP.
DEV Community — A space to discuss and keep up software development and manage your software career
Built on Forem — the open source software that powers DEV and other inclusive communities.
Made with love and Ruby on Rails. DEV Community © 2016 - 2026.
We're a place where coders share, stay up-to-date and grow their careers.
本页为82搜索生成的网页快照,内容来自站内索引;演示数据的原文链接仅作示例。