MISAR.md Project Rules
Two-layer configuration system that loads project conventions, coding standards, and architecture notes into every agent session automatically.
Overview
MISAR.md is a plain Markdown file that the agent reads at the start of every session. It lets you encode project conventions, preferred patterns, and architecture context so the agent behaves consistently across your whole team — without repeating yourself in every prompt.
The system has two layers that are always merged together:
| File | Scope | Purpose |
|------|-------|---------|
| ~/.misar/MISAR.md | Global — all projects | Personal preferences, editor habits, language defaults |
| .misar/MISAR.md | Project — current workspace | Stack conventions, architecture rules, team agreements |
Project rules take precedence when there is a conflict.
Auto-Generation
On first activation, Misar Code analyses your workspace and generates .misar/MISAR.md automatically. The generator scans:
package.json/pyproject.toml/Cargo.toml— stack and dependencies- Directory structure — monorepo layout,
src/,apps/,packages/ - Existing config files — linter, formatter, TypeScript settings
The result is a starter file with accurate stack information that you can extend immediately.
The auto-generated file is yours to edit. Misar Code never overwrites it after the initial creation.
Layer Behaviour
Global file loads first — ~/.misar/MISAR.md is prepended to the system context on every session, in every project.
Project file loads second — .misar/MISAR.md is appended after the global file, so project rules can override or extend global ones.
Agent applies both — the merged context shapes all tool calls, code generation, and decisions for the session.
What to Put in MISAR.md
# My Project
## Stack
- Framework: Next.js 15 App Router
- Language: TypeScript (strict mode)
- Styling: Tailwind CSS 4
- Database: PostgreSQL via Supabase client
- Package manager: pnpm
## Conventions
- Components live in `src/components/`, one file per component
- Server Actions go in `src/actions/`, named `<noun>-<verb>.ts`
- Never use `as any` — add missing types to the interface instead
- All DB queries go through `src/lib/db.ts`, never inline
## Architecture
- Auth is handled by the middleware in `src/middleware.ts`
- API routes are for external consumers only; UI uses Server Actions
- Feature flags live in `src/lib/flags.ts`
## Testing
- Unit tests: Vitest, co-located as `<file>.test.ts`
- E2E tests: Playwright in `tests/`
- Run `pnpm test` before committing
# Global Preferences
## Languages
- Default to TypeScript for all new files
- Python: use type hints, ruff for linting
- Go: follow standard project layout
## Code Style
- Prefer `const` over `let`; never use `var`
- Functional components only in React
- Explicit return types on all exported functions
## Commit Style
- Conventional Commits: feat, fix, chore, docs, refactor
- Subject line: imperative mood, max 72 chars
## Habits
- Always check for existing utilities before writing new ones
- Suggest tests when writing new business logic
Common Use Cases
Coding Conventions
Define naming patterns, file organisation, import order, and style rules the agent must follow.
Architecture Notes
Document which layers own which concerns so the agent places new code in the right location.
Preferred Patterns
Specify preferred libraries, state management approaches, or API design styles.
Banned Patterns
Explicitly list anti-patterns to avoid — the agent will flag or refuse to generate them.
Tips
- Keep each section short and directive. The agent responds better to rules (
"Use X","Never do Y") than to prose explanations. - Review the auto-generated file after creation and add the conventions your team actually cares about.
- Pair MISAR.md with
.misar/MEMORY.md— MISAR.md holds static rules while MEMORY.md accumulates learned context over time.
Use # OVERRIDE: as a heading prefix in .misar/MISAR.md to explicitly signal that a project rule supersedes a global one. The agent treats this as a strong directive.