chen08209
71 lines
5.1 KiB
Markdown
71 lines
5.1 KiB
Markdown
# 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](.agents/project.md): project overview, versions, and build dependencies.
|
|
- [.agents/commands.md](.agents/commands.md): build, development, code generation, and test commands.
|
|
- [.agents/rules.md](.agents/rules.md): lint, testing, generated-code, and workflow rules.
|
|
|
|
Read these only when the task touches their area:
|
|
|
|
- [.agents/architecture.md](.agents/architecture.md): core integration, providers, database, managers, build system, and
|
|
local plugins.
|
|
- [.agents/agent-config.md](.agents/agent-config.md): how to choose between `AGENTS.md`, `.agents`, skills, Codex config,
|
|
command rules, and hooks.
|
|
- [.agents/worktrees.md](.agents/worktrees.md): worktree hygiene across Claude Code, Codex, and Gemini.
|
|
- [.agents/flutter-upgrade.md](.agents/flutter-upgrade.md): SDK-pinned workarounds to recheck before changing the
|
|
Flutter version.
|
|
- [.agents/skills.md](.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](.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](.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](.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](.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.
|