Starter AI Rules

Português (PT-BR): README.pt-br.md · docs/pt-br/

Open-source development rules kit for AI agents (Cursor, Copilot, Claude Code, and similar). The goal is security, organization, code quality, and always-current context at every stage of a software lifecycle.

PT-BR and EN docs/rules must stay in the same state — see docs/en/i18n.md.

Why it exists

Coding AIs are powerful, but without clear guidelines they tend to:

• invent APIs and inconsistent patterns
• ignore security (secrets, auth, validation)
• generate code without tests or documentation
• let project context go stale (README, rules, ADRs)
• mix responsibilities and inflate scope

Starter AI Rules addresses this with a versioned, modular rules package adaptable to the team’s stack.

Principles

Principle	Meaning
Bilingual living context	PT-BR and EN docs/rules stay in sync (parity CI)
Docs + tests at every stage	Documentation and tests have priority in every phase — any language
Concise, complete rules	Short enough for the AI to load and apply all; no overlap or essays
Security first	Never expose secrets, never weaken auth, validate inputs
Living context	Documentation and rules follow the code — not “later”
One concern per rule	Short rules (≤ 20 lines), actionable, no repeating another rule
Verifiable quality	Tests on the project runner, lint, review, and CI as part of the AI flow
Minimal scope	Change only what was asked; no opportunistic refactors
alwaysApply budget	At most 8 core rules per language; detail via globs + docs/
Stack-agnostic	Core rules do not depend on language; stacks are optional extensions
Portability	Formats compatible with Cursor (.mdc), AGENTS.md, and adapters

What this repository delivers

starter_ai_rules/
├── rules/en/              # English rules
├── rules/pt-br/           # Portuguese rules (mirror)
├── docs/en/               # English docs
├── docs/pt-br/            # Portuguese docs (mirror)
├── scripts/install.sh     # --lang en|pt
├── templates/
├── README.md              # English (primary)
├── README.pt-br.md        # Portuguese
└── ROADMAP.md

Status: Phases 0–5 complete. To publish: fill in MAINTAINERS.md and tag v1.0.0 — see docs/en/release-checklist.md.

Quick start

1. Clone

git clone https://github.com/eudameron/starter_ai_rules.git
cd starter_ai_rules

2. Install into your project

./scripts/install.sh mvp /path/to/your/project --lang en   # recommended
./scripts/install.sh core /path/to/your/project --lang en
./scripts/install.sh full /path/to/your/project --lang en
./scripts/install.sh mvp /path/to/your/project --lang pt   # Portuguese pack

Creates .cursor/rules/ and AGENTS.md at the destination.

3. Adapt

Edit description / globs / alwaysApply on lifecycle/stacks rules as the team needs.

Cross-cutting priority

At every stage, the AI must treat documentation and tests as part of the delivery — not a later phase. Core rules (docs-and-tests-priority, tests-with-change, context-alive) apply to any language; only the runner/format already used by the repository changes.

Rules map (overview)

Stage	Domain	Docs + tests (required)	Other examples
Discovery	Scope and requirements	Testable acceptance criteria	Clarify ambiguities
Architecture	Design and ADRs	Documented decisions; validation plan	Layer separation
Setup	Bootstrap	How to run and test	Env, structure, tooling
Implementation	Code	Contracts/docs + tests for the change	Style, errors, typing
Testing	Quality	Coverage of the change / regression	Isolation, determinism
Security	Hardening	Abuse cases documented and tested when appropriate	Secrets, sanitization
Review	PR / diff	Docs checklist + test evidence	Atomic commits
Docs	Context	Sync README/rules	Changelogs, ADRs
Deploy / CI	Delivery	Release notes; do not bypass tests	Rollback, flags
Maintenance	Living context	Documented deprecations + regression	Sync rules ↔ code

Stage details: docs/en/etapas.md and ROADMAP.md.

Documentation

Document	Contents
docs/en/	English documentation
docs/pt-br/	Portuguese documentation
docs/en/i18n.md	PT-BR ↔ EN parity
README.pt-br.md	Portuguese README
ROADMAP.md	Delivery phases (0–5 ✅)
CONTRIBUTING.md	How to contribute

Compatibility

Tool	Supported format
Cursor	.cursor/rules/*.mdc
Generic agents	AGENTS.md
Copilot / Claude Code / Windsurf	docs/en/adaptadores/

Contributing

Read CONTRIBUTING.md and CODE_OF_CONDUCT.md.
Security: SECURITY.md. Maintainers: MAINTAINERS.md.

License

Distributed under the MIT license.