Effective System Prompts

A GEMINI.md file is a persistent system prompt. Every sentence in it shapes the model's behavior across an entire session. The difference between a mediocre system prompt and an expert one is specificity. "Write clean code" is a wish. "All functions must have explicit return types, use early returns for guard clauses, and include JSDoc comments with @param and @returns tags" is an instruction the model can follow consistently.

Effective system prompts follow a structure: identity (what the project is), constraints (what the model must and must not do), conventions (how code should look), and context (architectural decisions the model needs to understand). The order matters — identity and constraints should come first because they set the frame for everything that follows. Models weight earlier instructions more heavily than later ones, so your most critical rules belong at the top of the file.

# Payments Service (Critical Path)

## Constraints (read first)
- NEVER modify migration files after they have been applied
- NEVER log or print financial amounts, card numbers, or PII
- ALL monetary calculations use BigDecimal — never floating point
- ALL API responses must include idempotency_key validation

## Architecture
- Java 21, Spring Boot 3.2, PostgreSQL 16
- Event-driven: all state changes publish domain events
- CQRS: command handlers in /commands, query handlers in /queries

## Conventions
- Method names: verbNoun (processPayment, validateCard)
- Test names: should_expectedBehavior_when_condition
- Exceptions: domain-specific (PaymentDeclinedException, not RuntimeException)