sivtr AGENTS.md

AI Agent Instructions

This file is the single source of truth for AI coding assistants working on this project. Tool-specific instruction files, such as CLAUDE.md, should point here instead of duplicating these rules.

Keep this file limited to durable, cross-session guidance. Current progress, temporary state, and session scratch do not belong here.

Project

• Purpose:
• Stack:
• Package manager:

Commands

• Install:
• Dev:
• Test:
• Check:

Communication

• Use Simplified Chinese for user-facing explanations, questions, progress updates, and summaries.
• Keep code, identifiers, comments, logs, test names, and commit messages in English.
• Match the surrounding language when editing existing documentation.

Working Agreement

• Stay within the stated scope. Do not add, refactor, or improve unrelated functionality.
• Preserve unrelated working-tree changes and never discard user work.
• Follow the project's existing structure, conventions, and patterns.
• Adding, updating, or removing dependencies is allowed and encouraged when it benefits the project. Always propose the change first and wait for the user's explicit approval before applying it.
• If a request is ambiguous, risky, or has materially different approaches, explain the trade-offs and ask before changing files.
• If the safest path is clear and within scope, proceed and state any important assumption.
• Treat a request containing dry-run as read-only. Explain what would be done without modifying files or configuration.

Engineering Principles

• Make the smallest precise change that solves the problem; avoid unrelated refactoring.
• Identify business invariants and express each invariant in one authoritative place.
• Centralize shared validation, configuration, authorization, caching, and API contracts.
• Do not use broad try/catch blocks to swallow errors.
• Do not hide failures behind silent fallbacks.
• Prefer readable business flow over fragmented helper methods.
• Do not split a cohesive workflow into many one-use private methods.
• Introduce abstractions only for real reuse, a clear reduction in complexity, or an excessively long method.
• Use the Unix toolchain integrated into the terminal when it is the best fit for the task.