Project Instructions (AGENTS.md) · AI coding agents

Kimi Code CLI uses AGENTS.md as its instruction-file convention. Instruction-file content is injected into the system prompt as reference data (exposed to prompt templates as ${agents_md}) — it guides the agent but does not replace the system prompt.

Locations

File	Scope	Notes
`AGENTS.md` (project root)	Project	Committed to the repo; applies to everyone
`.kimi-code/AGENTS.md`	Project	Alternative in-tree location
`~/.kimi-code/AGENTS.md`	Global, Kimi-specific	Lives at `$KIMI_CODE_HOME/AGENTS.md`; moves with `KIMI_CODE_HOME`
`~/.agents/AGENTS.md`	Global, cross-tool	Real OS home; shared across tools; does NOT move with `KIMI_CODE_HOME`

? Unable to verify:

The exact AGENTS.md size/truncation limit. The changelog mentions a warning when AGENTS.md is truncated, but no numeric limit is documented.
Whether nested/subdirectory AGENTS.md files are merged hierarchically.
Whether CLAUDE.md files are read directly. Only the /import-from-cc-codex import path is documented (it imports Claude Code and Codex instructions, skills, and MCP settings into Kimi Code).

Generating instructions with /init

/init

/init analyzes the current codebase and generates an AGENTS.md for the project (idle-only). Review and commit the result — it becomes reference data in the system prompt of every future session in that repo.

SYSTEM.md override

$KIMI_CODE_HOME/SYSTEM.md permanently replaces the default main agent’s system prompt (the prompt only; description/tools/subagent allowlist are inherited). This is much stronger than AGENTS.md:

Precedence: project agent file with override: true and --agent-file > SYSTEM.md; --agent bypasses it; SYSTEM.md wins over same-name user-scope agent files.
Security note from the docs: project-level agent files (e.g. .kimi-code/agents/agent.md with override: true) from untrusted repos can take over the agent entirely — unlike AGENTS.md, which is only injected as data.

Example AGENTS.md

# AGENTS.md

## Project
Payments API — TypeScript monorepo (pnpm workspaces). Services live in `services/`,
shared libraries in `packages/`.

## Setup
- Node 22, pnpm 10. Install: `pnpm install`
- Copy `.env.example` to `.env` and ask a teammate for the sandbox keys.

## Commands
- Build:      `pnpm build`
- Test:       `pnpm test` (vitest); single file: `pnpm vitest run <path>`
- Typecheck:  `pnpm typecheck` — must pass before you consider a task done
- Lint:       `pnpm lint --fix`
- Dev server: `pnpm --filter api dev`

## Conventions
- ES modules, strict TypeScript, no `any` without a comment explaining why.
- Errors: use the `AppError` class from `packages/errors`, never throw raw strings.
- Database changes require a migration in `services/api/migrations/` — never edit
  the schema by hand.
- Commit messages: Conventional Commits (`feat:`, `fix:`, `chore:`).

## Boundaries
- Never commit `.env` or anything under `secrets/`.
- Do not modify `packages/proto/` — generated code; regenerate with `pnpm proto:gen`.
- Always run tests before finishing; do not mark work complete with failing tests.

Keep it short and operational: setup, commands, conventions, boundaries. The agent reads this every session, so prefer durable facts over prose.

Last verified: 2026-09-07

Official sources:

AI coding tools evolve quickly. If you find outdated information, please open an issue or pull request.