When you look at projects like Symfony, Astro or Ollama the first thing you see, after directories, are dot files.
Some tools abandoned the dot prefix and just use yaml or json files, and a rare xml file.
With AI tools we are seeing CLAUDE.md, AGENTS.md and other markdown files appear in the root directory.
For me this is straw that broke the camel's back.
The problem I have with the markdown files are the same that I have with the non-dot files, they miss context.
Dot files and folders are an old convention to signal configuration.
Most tools that use those configuration files have an option to specify the file. So it is possible to create a .tools folders and move all those files to that folder. Then use a makeFile to alias the tools with the config file.
The same could be done for AI markdown files.
The strange thing I discovered with Claude code is that it can use a .claude folder where you can place the config. But for scoping you need to add CLAUDE.md files to subfolders, this is worst than a root folder with many config files.
It looks like other people think scoping should be possible in .claude too.
What do you think? Is it time to clean up your application's root folder?
Update: After I wrote the post I found ai-coders-context. It seems to be more geared to switching from one AI tool to another. But it uses one folder, .context, to make it possible so it fits the cleaning root folder goal.
Top comments (3)
meh, configs can be in any file... ".env" just became popular because of the JS frameworks.
php projects used to all have .config.php files 20 years ago, and there's been various other formats/naming conventions.
It's just gonna keep changing because... welll, ANY file can be a config file if you want it to be.
That is the problem, when any file can be a config file how to distinguish the config files from the non config files?
People use markdown files for documentation, to generate pages in case of a static site generator and now AI context. Those are three distinct purposes. So how do you distinguish an AI context markdown file from a SSG file in the same directory? The simplest way I see is using a convention that is older than most developers.
My intuition is that dot files aren’t just configs — they’re meta-project configs. They signal tooling/environment concerns, not the project’s actual domain. That separation helps keep focus.
README.mdmakes sense as part of the project itself. Something likeCLAUDE.mdfeels more like tooling config and arguably belongs in the “dot file” category instead.