{"slug": "show-hn-shamefile-enforce-docs-for-linter-bypasses", "title": "Show HN: Shamefile – Enforce docs for linter bypasses", "summary": "A developer released Shamefile, a meta-linter that enforces documentation for linter bypasses by requiring developers to record the reason for each suppression in a YAML file. The tool, inspired by the Witcher game developers' regret over poor documentation practices, blocks undocumented linter warnings from passing CI checks. The creator reports that the tool has already changed AI agents' behavior during pre-commit phases, prompting them to fix code rather than add undocumented exceptions.", "body_md": "Recently, the creators of the Witcher games admitted that they regret not taking documentation seriously enough. As they work on the Witcher 1 remake, they are sometimes forced to reapproach old problems because the original reasoning was never properly recorded. A few veterans still remember the context, but some key decisions were made by people who left the studio years ago.\n\nWe all know the pain of undocumented decisions, so I built a meta-linter for linting other linters' warnings to fight my colleagues' laziness and my own (mostly). Maybe you just caught a lag from the number of lint words, but the idea is simple. Imagine a yaml file. Now add an entry to it:\n\n- location: ./the-file.rs:93 n\\ token: '// NOLINT' n\\ why: 'the reason' n\\\n\nDo you know what this NOLINT is? You don't? It's a suppression that you added 2 years ago. You don't remember? That's why you need shamefile. :)\n\nWhoever's fault it is. Yours or the linter's. It doesn't matter. Document it, make sure you understand the code, get a review of your new entry in shamefile.yaml and let CI verify it. With shamefile, your CI won't let any undocumented linter warning pass anymore. Instead of educating the business on why docs are important, you'll say: \"quality tools won't let my code pass\".\n\nI've observed a noticeable difference in AI agents' behaviour. During the pre-commit phase, reasoning models can \"rethink\" adding a new shame entry and actually fix the code. Not so easy now Claude, huh?\n\nThis is an early-stage tool. We've been using it in prod for a month now with my team and I'm using it in all my 3 OSS projects. Looking for feedback and contributors (adding new languages = good first issue ;))\n\nRepo: [https://github.com/BKDDFS/shamefile](https://github.com/BKDDFS/shamefile)\n\nComments URL: [https://news.ycombinator.com/item?id=48294118](https://news.ycombinator.com/item?id=48294118)\n\nPoints: 2\n\n# Comments: 0", "url": "https://wpnews.pro/news/show-hn-shamefile-enforce-docs-for-linter-bypasses", "canonical_source": "https://github.com/BKDDFS/shamefile", "published_at": "2026-05-27 13:33:34+00:00", "updated_at": "2026-05-27 13:48:36.884999+00:00", "lang": "en", "topics": ["ai-tools", "ai-agents"], "entities": ["Shamefile", "Witcher", "Claude"], "alternates": {"html": "https://wpnews.pro/news/show-hn-shamefile-enforce-docs-for-linter-bypasses", "markdown": "https://wpnews.pro/news/show-hn-shamefile-enforce-docs-for-linter-bypasses.md", "text": "https://wpnews.pro/news/show-hn-shamefile-enforce-docs-for-linter-bypasses.txt", "jsonld": "https://wpnews.pro/news/show-hn-shamefile-enforce-docs-for-linter-bypasses.jsonld"}}