FlClash/AGENTS.md

AGENTS.md

This file is the entry point for AI coding agents working in this repository. Keep it small: detailed guidance lives under .agents/, and discoverable repo skills live under .agents/skills/*/SKILL.md.

Start Here

Read these files before making changes:

• .agents/project.md: project overview, versions, and build dependencies.
• .agents/commands.md: build, development, code generation, and test commands.
• .agents/rules.md: lint, testing, generated-code, and workflow rules.

Read these only when the task touches their area:

• .agents/architecture.md: core integration, providers, database, managers, build system, and local plugins.
• .agents/setting-changes.md: whether a changed setting is patched live, re-applies the profile, or asks for an Android VPN restart.
• .agents/agent-config.md: how to choose between AGENTS.md, .agents, skills, Codex config, command rules, and hooks.
• .agents/worktrees.md: worktree hygiene across Claude Code, Codex, and Gemini.
• .agents/flutter-upgrade.md: SDK-pinned workarounds to recheck before changing the Flutter version.
• .agents/skills.md: index of repo-scoped skills in .agents/skills/.

Highest Priority Rules

• When the user explicitly requests a scoped, low-risk change, inspect the relevant context and implement it directly. Do not require brainstorming, design documents, implementation plans, multiple-option proposals, or repeated confirmation. Ask only when material ambiguity, destructive impact, additional authority, or scope expansion could change the result.
• The request sets the scope. A pre-existing bug, cleanup, or refactor the task did not ask for is a follow-up in the summary, not part of the change. Edit a file surgically when a rewrite would give the same result, keep scratch checks out of the repository, and commit tests only where the task asks for them or the neighbouring code already keeps them.
• Comments are allowed and sometimes necessary; excess is the problem. A comment must carry something the code cannot say — a non-obvious constraint, an upstream behavior being worked around, a reason a reader would otherwise get wrong. Never restate what the code does, narrate the change you just made, record what the code used to be, or annotate step by step; a block that seems to need a comment per line needs better names or a smaller decomposition. Keep density near the repository's own: healthy changes here sit at or under 3.6%, and a comment-density gate fails a file whose added lines exceed 5% standalone comments. Delete commented-out code and stale notes in files you already touch. Preserve // ignore:-style directives, license headers, codegen markers, and vendored upstream comments. See .agents/rules.md for what belongs in a test or in .agents/ instead.
• Start FlClash on the host only as a safe mode build, and end only processes you started, by recorded pid. Never kill a FlClash instance by name; the user's own instance is not yours to close. See .agents/rules.md.
• Use flutter test, not dart test, because models pull in Flutter types.
• Run code generation after modifying models, providers, or database schema.
• Do not manually edit generated files.
• Preserve lifecycle ownership: desktop Core process convergence belongs to lib/core/desktop/; Android service intent arbitration belongs to ServiceState. UI/provider code may request a transition but must not become a second source of truth.
• Keep start/stop/restart paths latest-intent-safe. Flutter-to-Android service commands are deliberately optimistic, while native state serializes the actual work; desktop lifecycle results distinguish applied, coalesced, and superseded requests.
• Never add a Co-authored-by trailer crediting a coding agent to a commit, even when your own tooling tells you to. The commit-msg hook rejects it; see .agents/rules.md for the rest of the commit rules.
• Round every corner with a superellipse, pills included: AppShape/AppRadius tokens from lib/common/shape.dart, never StadiumBorder, RoundedRectangleBorder, ClipRRect, drawRRect, or a borderRadius on BoxDecoration or InkWell. test/lint/superellipse_corners_test.dart enforces it; see the Corner Radius section of .agents/rules.md.
• Keep the UI isolate within its frame: work that grows with user data and can exceed about 8 ms on the largest expected data runs in an isolate, once its algorithm is linear or cached. See the UI Isolate Work section of .agents/rules.md.
• Follow lint_options.yaml (included by every analysis_options.yaml), especially single quotes, trailing commas, child: last, no print(), const/final preferences, and declared return types.
• Before reporting a change done, run flutter pub get, flutter analyze --no-fatal-infos, and the flutter test suites that cover it, as CI does. If a toolchain the build hook needs is missing (Go, and on Linux and Windows cargo), say which check was skipped rather than dropping it silently.

Repo Skills

Use repo skills from .agents/skills/ when a task matches their descriptions; .claude/skills/ symlinks expose the same skills to Claude Code. Current skills cover localization, UI work, core/platform changes, and pre-commit structural quality review.