A sensible approach to structuring projects in 2026

For all of 2026 I have yearned for a sensible approach to structuring projects in a way that doesn't lean too heavily into AI fads, but isn't ignorant of them, either. This structure is heavily rooted in existing engineering best practices while leaning into the capabilities we get from our new robot overlords.

The what

Let's dive into the exact folder structure first for the impatient types, and then we can unpack the reasons after.

.agents/
  skills/
    <name-of-skill>/
      SKILL.md
.claude
  skills/                <-- symlink to ../.agents/skills
  settings.json
  settings.local.json    <-- .gitignore'd
docs/
  adr/
    <0001-name-of-adr>.md
    README.md
  specs/
    <0001-name-of-work>/
      plan.md
      spec.md
    README.md
AGENTS.md
CLAUDE.md                <-- @AGENTS.md

The what in detail

.agents/ - The moment Codex became good, IT departments started forcing the use of Copilot, and open-weight models could do agentic work, we were no longer living in a pure Claude world.
.agents/skills - Similar to above, the moment OpenAI embraced the "open" format of SKILL.md, skills stopped being unique to Claude, and thus, needed a more agent-agnostic place to live.
.claude/ - There's no hiding the fact that the projects I work on heavily skew Claude and this is still a required folder.
.claude/skills - A symlink to .agents/skills. Claude is no longer the only user of skills.
.claude/settings.json - Project-wide settings useful for your peers. I tend to put npm scripts that should be safe to run so your fellow dev doesn't have to greenlight every tool use.
.claude/settings.local.json - .gitingore'd, but your own personal Claude prefs for this particular file.
docs/ - Notice this doesn't look "AI" shaped. Even if all your docs are written by agents (mine are), they're incredibly helpful for anyone wanting to get details about the project.
docs/adr - ADR stands for "Architecture decision records" this pattern predates agentic engineering, but having agents do the paperwork logging all the big decisions made for the project (and when) has proven to be incredibly helpful. If you're not familiar with ADRs, I'd recommend reading about them (or ask your favorite AI to explain them).
docs/specs - Specs are similar to ADRs, but more narrow in scope. A spec is what describes a particular body of work. In many ways, I think of specs as the new JIRA tickets.
docs/specs/<name-of-spec>/spec.md - A spec is a plain language outline of what you're trying to achieve. It contains the problem, known constraints, decisions, acceptance criteria, etc. If you've ever done Agile / Scrum, you can think of a spec as what would be the outcome of a refinement.
docs/specs/<name-of-spec>/plan.md - It sounds counter intuitive, but a plan is the tactical implementation of a spec. This includes retroactive changes once implementation begins and blockers are found. "If a spec is what we wanted, a plan is how we built it."
AGENTS.md - Once again we're reclaiming and genericizing something Claude originally popularized.
CLAUDE.md - A simple symlink to keep Claude happy.

How I work

To know if the above would be a good fit for you and your projects, it might be useful to frame how I work as it relates to AI. Here we go:

Is it easily testable? I'm not writing any code. This is 100% AI.
Is it UX? I'm probably writing most the code and kicking out to AI for lower-level data wrangling or reviewing my work for small logic-orriented bugs.
Is this research? If I'm tossing around some ideas I want to research, I'm not writing any code, either. This is regardless of UX... I will prompt Claude with something like, "Can you make a demo page that has full viewport sized sections and as I scroll to one it snaps into place? I don't want any scroll speed hijacking, I just want the sections to snap. Bonus points for a CSS-only solution."

Agents are incredibly good these days at binary outcomes. "This API should return this shape under these conditions."

Agents are currently horrible when you need absolute UX precision. "That animation seems to be blowing out that bounding box while the other animation seems to pop in at the wrong time." You'll be prompting and praying for hours if you think Claude is going to fix these types of problems. This isn't binary, either... every once in a while, Claude won't write trash CSS.

This sort of "dual personality" meant my node-based projects had all sorts of specs, plans, and AGENTS.md. My UI-based projects were left in human-curated land. The project structure I propose above fits in well with both projects.

When and why

When to spec

Unless something is a line or two, I will almost always have Claude write a spec. Even if I'm the one doing the work, I want to talk through my own knowledge of the task, I want Claude to be my sounding board, etc. Claude can scan the codebase and fact you much faster than you can with your own meat fingers. I'd recommend having a README.md that outlines when a spec is needed and when it isn't.

Fun fact: I have an open 60+ hour conversation with Claude on a topic I've been revisiting for months now.

When to ADR

If you make a decision that will impact the entire project, write an ADR. You will likely not remember your original motivations and both future you and past you will thank you.

When to AGENTS.md

The contents of this file has already been debated for years. My personal take: if something is easily knowable from the codebase, it does not belong in AGENTS.md. If an agent can run ls -l and see a file list, you don't need to add your file list in AGENTS.md. You should constantly be asking, "Can an agent figure this out quickly through its existing world knowledge or by simply reading a file?" if the answer is yes, it doesn't go in. AGENT.md is for nuance and context that cannot be easily gained just by reading files.

A practical example

What I have above is the result of roughly a year of refinements working in both big and small projects. It's the result of being dissatisfied with how UX-orriented projects felt underserved from an AI perspective (or even laughably premature - "we must have a CLAUDE.md!"), while node-based projects felt overserved and a bit arbitrary... thanks Superpowers!

I felt strong enough about the above guidance and patterns that we shipped this exact structure in Author Kit. You can see all the above reasoning and structure applied to a real codebase with real needs.

Closing out

It's probably obvious from above, but I'm a huge believer in spec-driven development (SDD). I think it re-purposes existing engineering conventions and brings them forward for this new agentic era we're living in. These conventions feel fad-proof in a way I haven't seen thus far.