Linting the Shape of a Repository | Hacker News Reader

Linting the Shape of a Repository

alint.org

1 pointaleqs3 comments

Not sure if this is in relation to traditional/manual codebases or if we are talking about one where AI agents contribute heavily. In my own agentic flow I prioritize: - Directories: - /plan - it contains every implementation plan and test scenarios for every new major feature. - /test - with Unit and BDD tests files and scripts -/Docs - ofcourse all documentation - Agent or Claude.md + Plan.md that serves as roadmap - NON NEGOTIABLE - Others: Zod, Monorepo, git etc and other engineering/architecture good practices - CI/CD

I hope that helps.

This is for both manual/human and agentic codebases. Many/most repos already have conventions/rules which are somewhat implicit and only enforced manually via code reviews. In repos that heavily use agents/AI I feel that having some sort of strict and deterministic enforcement is even more useful - AGENTS.md works pretty well, but it is not deterministic or actually enforced in any way - agents can ignore or forget about what AGENTS.md says, and this becomes more and more apparent as a repo grows - the conventions are slowly and incrementally violated, incorrectly placed/named/structured files compound and confuse the agent more and more - the mess keeps growing. alint does integrate and play well with AGENTS.md - it can export the ruleset it defines into AGENTS.md in a agent-friendly/readable way. It can also explain a deterministic rule to an agent and help it figure out how to fix a violation.

Author here, 'the shape of a repository' refers to the structure/organization of files/directories, file naming conventions, unicode conventions (do not allow invisible Unicode for example), making sure build artifacts aren't committed, max file size, etc. Requiring files like LICENSE, README.md, etc exist. Anything about the structure/conventions of a repo that isn't actual code (a language specific linter should be used for the actual code).

Would be interested to hear what other kinds of conventions/rules you guys find useful to enforce for a repo, and how you currently do that.

Reply on news.ycombinator.com