Structuring your workspace

A folder is how you give an agent context, so the way you lay one out matters. A clear structure helps both your team and your agent find things without hunting.

Start with the files that keep it current

The most valuable part of a workspace is the small set of files that let it keep itself current. Add them from the start:

• CLAUDE.md and AGENTS.md at the root, so every agent knows who you are and how the workspace is organized.
• A README in each folder, so each folder explains itself.
• lessons.md, so your agents learn what to do differently and stop repeating mistakes.
• log.md, so the team remembers the decisions and changes that matter.

Together these make the workspace self-updating: your agent reads them at the start of a session and updates them as you work, so the structure stays honest instead of going stale.

Principles

• Name folders for the work, not the tool. Prefer accounts/, campaigns/, hiring/ over docs/ or misc/.
• Keep it shallow. A few clear top-level folders beat deep nesting.