NAME
.goosehints — instruction file for Goose
SYNOPSIS
./.goosehints.default
./.goosehints
~/.goosehints
./.goosehints.local
METADATA
DESCRIPTION
`.goosehints` is the instruction file for Goose, Block's open-source AI coding agent. The file content is appended to Goose's system prompt, providing project context and coding conventions.
Goose supports a four-level priority chain: `.goosehints.default` (lowest, committed), `.goosehints` (standard, committed), `~/.goosehints` (global, personal), and `.goosehints.local` (highest, not committed). The highest-priority file found takes effect.
The file uses plain text format — Markdown formatting is fine for readability but there's no special schema, frontmatter, or directive syntax. Goose reads the content and injects it directly into the system prompt context.
Lower numbers load first. Higher-priority files override lower ones.
STRUCTURE
ANNOTATED EXAMPLE
1# Project: Inventory Management API
2
3Built with Go 1.22, Chi router, and PostgreSQL.
4Deployed on Google Cloud Run.
5
6## Code Conventions
7- Follow Go standard project layout
8- Use table-driven tests
9- Error wrapping with fmt.Errorf("operation: %w", err)
10- Context propagation: always pass ctx as first parameter
11- Use sqlc for type-safe database queries
12
13## Architecture
14- cmd/server/ — Main entrypoint
15- internal/api/ — HTTP handlers
16- internal/service/ — Business logic
17- internal/repo/ — Database layer (sqlc generated)
18- migrations/ — SQL migration files
19
20## Commands
21- make run — Start dev server
22- make test — Run all tests
23- make migrate-up — Apply pending migrations
24- make lint — Run golangci-lint
25
26## Important
27- Never use global state or init() functions
28- All database access goes through the repo layer
29- Use structured logging with slog package
COMMON MISTAKES
The .local variant is designed for individual developer preferences that shouldn't be shared with the team. It has the highest priority and will override all other hint files.
Goose uses a priority chain (.goosehints.local > ~/.goosehints > .goosehints > .goosehints.default) but the behavior is replacement, not merge. The highest-priority file found is the one that gets used.
Goose treats the file content as plain text that gets appended to the system prompt. You can use Markdown for readability, but there's no special parsing of headings, frontmatter, or directives.