DEV Community

Prism Team
Prism Team

Posted on

I built a validated alternative to CLAUDE.md/AGENTS.MD — meet GUIDE.md

#ai #opensource #webdev #productivity

If you've used Claude, Cursor, or Copilot on a real project, you've probably created a CLAUDE.md or agents.md file — a markdown file that tells the AI about your codebase.

The problem is there's nothing stopping that file from being wrong.

You declare language: typescript but the project is now Python. You list entry points that no longer exist. Your version numbers drift from what's actually in package.json. The AI reads your context file, trusts it, and works from bad information.

That's why I built GUIDE.md.

What is GUIDE.md?

GUIDE.md is a validated, drift-aware AI context standard. It's the same idea as CLAUDE.md — a file that gives AI agents structured context about your project — but with one key difference:

It can be wrong. Which means it can be verified.

How it works

A GUIDE.md file has two parts:

YAML frontmatter — machine-readable metadata validated against a schema:

---
guide_version: "1.0.0"
project: "my-app"
language: python
framework: fastapi
strict_typing: false
error_protocol: verbose
guardrails:
  no_hallucination: true
  scope_creep_prevention: true
context:
  entry_points:
    - "src/main.py"
  off_limits:
    - ".env"
---
Enter fullscreen mode Exit fullscreen mode

Markdown body — human and AI readable instructions:

## Project Overview
## Domain Vocabulary
## Non-Obvious Decisions
## What NOT to do
Enter fullscreen mode Exit fullscreen mode

The CLI tool 

npm i -g @prismteam/linter
Enter fullscreen mode Exit fullscreen mode

Initialize in any project:

guidemd init
Enter fullscreen mode Exit fullscreen mode

Auto-detects your language, framework, paradigm, runtime, and entry points — across TypeScript, Python, Go, Rust, Java, Ruby, PHP, Swift, Dart, Elixir and more.

Validate:

guidemd lint
Enter fullscreen mode Exit fullscreen mode

Catches missing required fields, stale dates, weak descriptions, and exposed secrets.

Detect drift:

guidemd sync
Enter fullscreen mode Exit fullscreen mode

Compares your declared versions against actual package.json, requirements.txt, Cargo.toml, go.mod and warns you when they diverge.

Export to every format:

guidemd export
Enter fullscreen mode Exit fullscreen mode

Generates CLAUDE.md, .cursorrules, .windsurfrules, AGENTS.md, .github/copilot-instructions.md and .aider.conf.yml from one source of truth.

Why not just use CLAUDE.md?

CLAUDE.md GUIDE.md
Schema validation ❌ ✅
Drift detection ❌ ✅
Auto-detection ❌ ✅
Multi-format export ❌ ✅
Secret scanning ❌ ✅
MCP server ❌ ✅

CLAUDE.md is a convention. GUIDE.md is a standard.

Try it 

npx @prismteam/linter init
Enter fullscreen mode Exit fullscreen mode

The repo is open source — feedback and contributions welcome.

Top comments (0)