Ask HN: How are you structuring Markdown-based context for AI coding agents?

I’ve recently transitioned from using LLMs in-browser to a local agentic workflow in VS Code (Gemini Code Assist). I can approve/disapprove changes which is nice, but I’ve hit a wall regarding context management. Initially, I provided all the whole repo as context to the non-agentic version of Gemini code assist and it performed well.

I read the agentic mode is "better" so to keep the agent aligned with my project's architecture, I’ve manually built 7 dense Markdown files that serve as the system instructions for the project. I require Gemini to update these files as we implement features.

gemini.md (instructs gemini to read the other md files and handle updating) project_overview.md, architecture.md, features.md, database.md, api.md, security.md

Each file is between 500–1,500 words so I’m concerned if f this is the right way to go. There seems to be no consensus on context file best practices. I’m seeing strong arguments for both minimalist, lean instructions and dense, project-wide specs. Honestly, the proper usage/prompting patterns of LLM's seems to be comparable to reading horoscopes, everyone goes by gut-feeling with the most cited source of truth being the confirmation bias.

How are you using .md context files in your workflow?