Are markdown files becoming the new dot files?

Source: Dev.to

Background

Projects such as Symfony, Astro, and Ollama often place dot files (e.g., .gitignore, .env) at the top level of the repository.

With the rise of AI tools, new markdown files like CLAUDE.md, AGENTS.md, and similar are appearing in the root directory as well.

Issues with Markdown Configuration Files

• Lack of context – Like other non‑dot files, these markdown files can be hard to locate and understand without additional documentation.
• Cluttered root – Adding more files to the repository root makes the project structure harder to navigate.

Possible Solutions

1. Create a dedicated folder
   Place all configuration‑related markdown files in a .tools (or similar) directory.

   # Example directory structure
   .
   ├── src/
   ├── .tools/
   │   ├── CLAUDE.md
   │   └── AGENTS.md
   └── Makefile

2. Use a Makefile (or similar) to alias tools
   Define targets that reference the configuration files inside the dedicated folder.

   # Makefile example
   claude:
   	@echo "Running Claude with config .tools/CLAUDE.md"
   	# command that uses the config file
   
   agents:
   	@echo "Running Agents with config .tools/AGENTS.md"
   	# command that uses the config file

3. Scope within the markdown files
   Some developers suggest adding scoping mechanisms directly inside files like CLAUDE.md to avoid the need for separate directories.

Discussion

Is it time to clean up your application’s root folder by moving AI‑related markdown files into a dedicated directory and using aliases? This approach can improve organization, reduce clutter, and make the purpose of each file clearer.