| name | agenty-conventions |
| description | Project-specific coding conventions and patterns for the agenty repository. Covers Go 1.26 style rules, GORM query patterns, embedded DB schema, Gin route conventions, tool registration, model/DTO design, and BM25/vector search usage. Must be loaded whenever adding new code to the agenty codebase. |
| license | Apache-2.0 |
| metadata | {"author":"masteryyh","version":"1.0.0","domain":"project-conventions","triggers":"agenty, Go service, GORM, SQLite, PostgreSQL, Gin route, tool registration, BM25, ParadeDB, FTS5, service pattern, model DTO","role":"specialist","scope":"implementation","output-format":"code"} |
agenty Project Coding Conventions
agenty is an AI Agent application written in Go 1.26. It consists of a backend service (Gin + GORM + SQLite/PostgreSQL) and a CLI client, supporting tool calling, agentic looping, and a skills system.
Hard Rules (Non-Negotiable)
- All new Go source files must include the Apache 2.0 license header (see
references/go-conventions.md)
- No redundant comments unless explicitly requested by the user
- No summary documents or planning documents
- Always reply to the user in Simplified Chinese
- Use
any instead of interface{}
- Use
fmt.Fprintf instead of strings.Builder.WriteString()
- GORM
Raw().Rows() must use ? placeholders — never use $1/$2 directly
- JSON field names and JSON tags must use lowerCamelCase for API/tool request and response payloads
- Do not use GORM
AutoMigrate; table definitions live in embedded SQL under pkg/conn/db
- Persistent GORM model structs should avoid database-specific
gorm tags; keep schema details in SQL files
Detailed Coding Patterns
- Avoid String Concatenation in
WriteString: When using strings.Builder, do not use string concatenation (+) inside WriteString. Instead, split them into multiple sequential WriteString calls (e.g., buf.WriteString(A); buf.WriteString(B) instead of buf.WriteString(A + B)).
- Use Built-in
min/max: Use Go's built-in min() and max() functions instead of manual if statements for clamping or comparing values.
- Use
strings.SplitSeq: When iterating over split strings, use strings.SplitSeq instead of strings.Split to prevent unnecessary slice allocations.
Package Structure Quick Reference
| Package Path | Responsibility |
|---|
pkg/models/ | GORM data models + DTO structs |
pkg/services/ | Business logic, singleton pattern |
pkg/routes/ | Gin route handlers, singleton pattern |
pkg/chat/tools/builtin/ | Built-in tool implementations |
pkg/chat/tools/tool.go | Tool interface definition and global registry |
pkg/conn/ | DB, HTTP client, SSE, GORM logger |
pkg/conn/db/ | Embedded PostgreSQL/SQLite schema SQL |
pkg/customerrors/ | Business error definitions |
pkg/utils/response/ | Gin unified response helpers |
pkg/utils/safe/ | Safe goroutine launcher |
pkg/utils/signal/ | Global base context |
pkg/consts/ | Constants; tool description strings go here |
pkg/backend/ | Backend interface + Local/Remote implementations |
Reference Index
| Topic | File | Load When |
|---|
| Go syntax conventions | references/go-conventions.md | Creating or modifying any Go file |
| Service layer patterns | references/service-patterns.md | Adding/modifying pkg/services/ |
| Route patterns | references/route-patterns.md | Adding/modifying pkg/routes/ |
| Tool patterns | references/tool-patterns.md | Adding a new built-in tool |
| Database patterns | references/database-patterns.md | Working with GORM, schema SQL, BM25, FTS5, sqlite-vector, or ParadeDB |
Implementation Checklist
Verify each item when adding new functionality: