DEV Community

dotori
dotori

Posted on

I built a linter for AI project structure — because every project looked different

#cli #vibecoding #ai #opensource

The problem nobody talks about

Here's a pattern I kept running into:

I'd start a new project with Claude Code, get into a flow, build something real — and then look at the folder structure a week later and wonder who made these decisions.

Start 10 projects with AI coding tools, and you'll get 10 different structures. One has CLAUDE.md, another doesn't. One has .claude/hooks.json, three others don't even have a .claude/ directory. Documentation lives in docs/ in one project and nowhere in the next.

Then a teammate joins and the first message is always: "Where's the config? Do we have hooks set up? Is there a plan document somewhere?"

The AI tools themselves suffer from this too. Claude Code works better when it has structured context — agent definitions, skill files, templates, policies. But there's no built-in way to check whether your project actually has all of that in place.

I wanted something like ESLint, but for project layout.

So I built bkit-doctor

bkit-doctor is a CLI that diagnoses your AI-assisted project structure and fixes what's missing — in one command.

npx bkit-doctor check
Enter fullscreen mode Exit fullscreen mode 
bkit-doctor v1.0.0

  Project Structure Check
  ────────────────────────────────────
  [PASS]  .claude/ directory
  [PASS]  CLAUDE.md
  [FAIL]  .claude/hooks.json
  [FAIL]  .claude/settings.local.json
  [WARN]  docs/01-plan/
  [WARN]  docs/02-design/
  [PASS]  docs/03-task/
  [PASS]  docs/04-report/
  [FAIL]  Agent definitions (4 files)
  [FAIL]  Skill files (7 files)
  ...

  Result: 6 PASS · 2 WARN · 6 FAIL
  Recommendation snapshot saved.
Enter fullscreen mode Exit fullscreen mode

Then fix everything:

npx bkit-doctor fix --yes
Enter fullscreen mode Exit fullscreen mode

That's it. Missing directories created, config files scaffolded, agent definitions generated — all without touching anything that already exists.

Three things that matter

1. Diagnose: 14 checks, one command

bkit-doctor check inspects your project for 14 items across 6 categories: directory structure, config files, documentation scaffolds, agent definitions, skill files, templates, and policies.

Hard failures (missing .claude/ or CLAUDE.md) return exit code 1. Everything else is a warning. Simple.

2. Fix: scaffold what's missing

bkit-doctor fix --yes runs diagnosis, figures out what's missing, and creates it. One command, no prompts.

Want to see what it would do first?

bkit-doctor fix --dry-run
Enter fullscreen mode Exit fullscreen mode

You can also pick specific targets:

bkit-doctor init --target hooks-json
bkit-doctor init --targets agents-core,docs-core
Enter fullscreen mode Exit fullscreen mode

Or use presets for different project sizes:

bkit-doctor preset list
# default  — full structure (8 targets)
# lean     — minimal (config + agents only)
# workflow-core — agents + skills + templates + policies
# docs     — documentation scaffold only
Enter fullscreen mode Exit fullscreen mode

3. Safe by design

This was non-negotiable: existing files are never overwritten unless you explicitly pass --overwrite. Even then, --backup creates copies before touching anything.

No surprises. No lost work. Preview everything with --dry-run.

When you'd actually use this

Starting a new project:

mkdir my-app && cd my-app
git init
npx bkit-doctor fix --yes
# Full AI-friendly project structure in seconds
Enter fullscreen mode Exit fullscreen mode

Adding structure to an existing project:

cd existing-project
npx bkit-doctor check          # see what's missing
npx bkit-doctor fix --dry-run  # preview the fix
npx bkit-doctor fix --yes      # apply it
Enter fullscreen mode Exit fullscreen mode

CI gate for project health:

# .github/workflows/check.yml
- name: Verify project structure
  run: npx bkit-doctor check
  # exits 1 if .claude/ or CLAUDE.md is missing
Enter fullscreen mode Exit fullscreen mode

About bkit

bkit-doctor was inspired by bkit, a PDCA-based development workflow framework for Claude Code. I learned a lot about structured AI collaboration from bkit's methodology, and that shaped how this tool thinks about project structure.

That said — bkit-doctor is fully independent. It doesn't require bkit, doesn't include bkit code, and works with any AI coding tool. If you do use bkit, the scaffolding is optimized for its workflow. If you don't, you still get a clean, well-organized project structure.

Try it 

npx bkit-doctor check
Enter fullscreen mode Exit fullscreen mode

If this solves a problem you've had, a star on the repo would be appreciated. And if you have ideas for additional checks or presets, issues and PRs are welcome.

bkit-doctor is an independent open-source project (Apache 2.0). It is not affiliated with the bkit team.

Top comments (0)