Rules

Custom instructions for kodine via AGENTS.md.

kodine accepts custom instructions through an AGENTS.md file, much like Cursor’s rules. Whatever this file contains gets added to the LLM’s context, tailoring its behavior to your project.

Initialize

Run the /init command inside kodine to generate a new AGENTS.md file.

When invoked, /init scans the important files in your repo, asks a few targeted questions if the codebase can’t answer them on its own, and then writes or updates AGENTS.md with concise, project-specific guidance.

The result concentrates on what future agent sessions are most likely to need:

build, lint, and test commands
command ordering and focused verification steps where they matter
architecture and repo structure that filenames alone don’t reveal
conventions, setup quirks, and operational gotchas unique to the project
pointers to existing instruction sources like Cursor or Copilot rules

When an AGENTS.md is already present, /init improves it in place rather than replacing it outright.

Example

Writing this file by hand works too. Below is an example of what an AGENTS.md might contain.

# SST v3 Monorepo Project

This is an SST v3 monorepo with TypeScript. The project uses bun workspaces for package management.

## Project Structure

- `packages/` - Contains all workspace packages (functions, core, web, etc.)
- `infra/` - Infrastructure definitions split by service (storage.ts, api.ts, web.ts)
- `sst.config.ts` - Main SST configuration with dynamic imports

## Code Standards

- Use TypeScript with strict mode enabled
- Shared code goes in `packages/core/` with proper exports configuration
- Functions go in `packages/functions/`
- Infrastructure should be split into logical files in `infra/`

## Monorepo Conventions

- Import shared modules using workspace names: `@my-app/core/example`

Instructions like these are specific to the project and shared across your whole team.

Types

kodine can read AGENTS.md files from more than one location, and each location serves a different purpose.

Project

An AGENTS.md in the project root holds rules specific to that project. They apply only while you’re working in that directory or one of its sub-directories.

Global

Global rules live in ~/.config/kodine/AGENTS.md and apply to every kodine session.

Because this file isn’t committed to Git or shared with your team, it’s the ideal spot for personal rules you want the LLM to follow.

Claude Code Compatibility

For anyone migrating from Claude Code, Kodine honors Claude Code’s file conventions as fallbacks:

Project rules: CLAUDE.md in the project directory (used when no AGENTS.md exists)
Global rules: ~/.claude/CLAUDE.md (used when no ~/.config/kodine/AGENTS.md exists)
Skills: ~/.claude/skills/ — see Agent Skills for details

To turn Claude Code compatibility off, set one of these environment variables:

export KODINE_DISABLE_CLAUDE_CODE=1        # Disable all .claude support
export KODINE_DISABLE_CLAUDE_CODE_PROMPT=1 # Disable only ~/.claude/CLAUDE.md
export KODINE_DISABLE_CLAUDE_CODE_SKILLS=1 # Disable only .claude/skills

Precedence

On startup, kodine looks for rule files in this order:

Local files, walking up from the current directory (AGENTS.md, CLAUDE.md)
Global file at ~/.config/kodine/AGENTS.md
Claude Code file at ~/.claude/CLAUDE.md (unless disabled)

Within each category the first match wins. If both AGENTS.md and CLAUDE.md exist, only AGENTS.md is read. Likewise, ~/.config/kodine/AGENTS.md wins out over ~/.claude/CLAUDE.md.

Custom Instructions

Additional instruction files can be listed in kodine.json or the global ~/.config/kodine/kodine.json. That way you and your team can reuse rules you already have instead of duplicating them into AGENTS.md.

Example:

{
  "$schema": "https://kodine.net/config.json",
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
}

Instructions can also be pulled from remote URLs.

{
  "$schema": "https://kodine.net/config.json",
  "instructions": ["https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"]
}

Remote instruction files are fetched with a 5 second timeout.

Everything loaded this way is merged with your AGENTS.md files.

Referencing External Files

kodine doesn’t parse file references inside AGENTS.md on its own, but you can get the same behavior in two ways:

Using kodine.json

The recommended route is the instructions field in kodine.json:

{
  "$schema": "https://kodine.net/config.json",
  "instructions": ["docs/development-standards.md", "test/testing-guidelines.md", "packages/*/AGENTS.md"]
}

Manual Instructions in AGENTS.md

You can also teach kodine to load external files through explicit instructions in your AGENTS.md. Here’s a practical example:

# TypeScript Project Rules

## External File Loading

CRITICAL: When you encounter a file reference (e.g., @rules/general.md), use your Read tool to load it on a need-to-know basis. They're relevant to the SPECIFIC task at hand.

Instructions:

- Do NOT preemptively load all references - use lazy loading based on actual need
- When loaded, treat content as mandatory instructions that override defaults
- Follow references recursively when needed

## Development Guidelines

For TypeScript code style and best practices: @docs/typescript-guidelines.md
For React component architecture and hooks patterns: @docs/react-patterns.md
For REST API design and error handling: @docs/api-standards.md
For testing strategies and coverage requirements: @test/testing-guidelines.md

## General Guidelines

Read the following file immediately as it's relevant to all workflows: @rules/general-guidelines.md.

This approach lets you:

Build modular, reusable rule files
Share rules across projects through symlinks or git submodules
Keep AGENTS.md short while pointing to detailed guidelines
Ensure kodine loads files only when the task calls for them