Skip to content

AGENTS.md

Latest commit

 

History

History
66 lines (49 loc) · 3.51 KB

AGENTS.md

File metadata and controls

66 lines (49 loc) · 3.51 KB
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Agent Development Guidelines

This document defines the core standards and operational protocols for agents working on the Opencode codebase.

Opencode is a Bun-powered monorepo for AI-driven development. It utilizes a high-performance stack including TypeScript 5.8+, SolidJS, and SST. The architecture emphasizes erasable syntax, minimal runtime overhead, and strict type safety.

1. Commands & Operations

  • Development: MUST run bun dev to start the core Opencode application.
  • Testing:
    • Root tests are disabled. MUST run tests from within specific package directories (e.g., cd packages/opencode && bun test).
    • To test Opencode specifically, use bun dev in packages/opencode.
  • Typechecking: SHOULD use bun run typecheck (Turbo-powered) for workspace-wide validation.
  • SDK: MUST regenerate the JavaScript SDK using ./packages/sdk/js/script/build.ts after API changes.
  • Git: The default branch is dev.
  • Fork Syncing:
    • Agents MUST stash the .opencode folder before syncing with upstream.
    • Agents MUST NOT sync the .opencode folder from upstream.
    • Ensure NO EXTRA FILES (untracked or new upstream files) are accidentally added during sync.

2. Coding Standards

Structure & Organization

  • File Headers: Every file MUST start with a 2-3 sentence comment explaining its purpose.
  • File Size: Files SHOULD NOT exceed 200 lines. Files over 300 lines MUST be split.
  • Function Size: Functions SHOULD NOT exceed 40 lines.
  • Barrels: Every module directory MUST have an index.ts file. Consumers MUST import from the barrel, not deep paths.
  • Domain Separation: Organize code by business domain, not technical layers.

Style & Logic

  • Minimalism: Avoid try/catch and else statements where possible. Prefer "Fail Fast" patterns.
  • Variables: PREFER single-word variable names. AVOID let statements and unnecessary destructuring.
  • Logging: MUST NOT use console.log, console.error, or other logging. Trust the type system.
  • DRY: Pattern recognition is mandatory. Abstract similar code immediately into shared utilities.

Type System

  • Strictness: MUST NOT use any. Use unknown and narrow via control flow.
  • Types vs Interfaces: Prefer type for data shapes; use interface only for extensible public APIs.
  • Erasable Syntax: MUST NOT use enum, namespace, or constructor parameter properties.
  • Imports: MUST use import type for type-only imports and MUST include .js extensions in Node.js compatible imports.

3. Tool Usage & AI Protocols

  • Parallelism: Agents MUST use parallel tool calls whenever multiple independent operations are possible.
  • Verification: Agents MUST verify code changes by running relevant tests or build commands before reporting completion.
  • XML Tags: Documentation and instructions SHOULD use XML tags (e.g., <instructions>, <workflow>) for clarity as per RFC-XML-STYLE-GUIDE.md.
1. **Explore**: Read relevant barrel files and existing implementations before writing new code. 2. **Implement**: Write code following the "Fail Fast" and "No Else" rules. 3. **Validate**: Run package-specific tests and typechecks. 4. **Clean**: Remove any temporary files or debug statements before submission.