.agents

Imported from yRickzC/PES_RPT (.agents/AGENTS.md). Install upstream with npx skills add yRickzC/PES_RPT --skill .agents. Copyright stays with the author.

Engineering Architecture & Code Generation Rules

1. Core Principles

These rules are mandatory.

Every task must follow these principles:

1. Never modify or create anything without explicit authorization.
2. Every generated solution must have a functional architecture.
3. All code must be written in English and must not contain comments.
4. The existing coding style defined in this document must be preserved.

If any rule conflicts with a direct instruction from the user, the user's explicit instruction takes precedence only for that specific task.

2. Strict Context Boundary

The files explicitly provided in the prompt are the entire available project context.

You MUST NOT:

• Read files that were not explicitly provided.
• Modify files that were not explicitly provided.
• Create files in directories that were not explicitly authorized.
• Assume the existence of files, classes, services, components, modules, or directories that were not provided.
• Infer missing project architecture from common conventions.
• Create "helper" files, utilities, abstractions, interfaces, configurations, tests, or other files unless their creation is explicitly authorized.
• Use external project context that was not included in the prompt.

The provided files are the complete source of truth for the task.

2.1 Missing Context

If completing the task requires information that is not present in the provided context:

STOP.

Do not guess.

Do not create a workaround.

Do not create an additional file to compensate for missing context.

Do not modify an unrelated file.

Report exactly what context is missing and why it is required.

Example:

Task blocked: ItemRepository is required to implement this functionality, but its implementation was not provided and its creation was not explicitly authorized.

The correct behavior is to fail the task instead of making architectural assumptions.

3. Explicit File Authorization

File creation and modification are strictly controlled.

3.1 Existing Files

An existing file may only be modified when:

• The file was provided in the prompt.
• The requested task requires modifying it.
• The modification is consistent with the explicit task.

Never modify an existing file merely because it would make the architecture "better".

Do not perform unrelated refactoring.

Do not clean up unrelated code.

Do not rename unrelated variables.

Do not reorganize unrelated directories.

Do not optimize unrelated functionality.

3.2 New Files

A new file may only be created when its creation is explicitly authorized by the prompt.

The prompt must provide enough information to determine:

• The file path.
• The purpose of the file.
• Its responsibility.
• Its relationship with the existing architecture.

If the required directory or location is not authorized:

FAIL THE TASK.

Do not decide where the file should go yourself.

For example, if the task requires creating a new ItemComponent, but no location for new components was authorized, stop and request the missing context.

4. Single Responsibility Architecture

Every file must have one clear responsibility.

A file should exist because it performs one specific architectural role.

Do not create files that accumulate unrelated responsibilities.

Bad:

Item
├── item data
├── inventory management
├── item rendering
├── item persistence
├── item validation
├── item networking
└── item spawning

Good:

Item
ItemRenderer
ItemRepository
ItemValidator
ItemSpawner

Each unit has a focused responsibility.

The exact architecture depends on the project and technology, but the principle remains universal.

5. Functional Architecture

Architecture must be organized around functionality and responsibility, not arbitrary file size.

Do not split code merely because a file has many lines.

Do not keep everything inside one class merely because it technically works.

The correct question is:

"Does this unit have one coherent responsibility?"

If the answer is no, split it.

5.1 When a Class Becomes Too Large

If a class starts handling multiple independent responsibilities, change the architecture.

Example:

Item
├── item state
├── item rendering
├── item interaction
├── item inventory logic
├── item persistence
└── item networking

Do not keep expanding Item.

Instead, identify the independent responsibilities and separate them according to the project's architecture.

For example:

Item
ItemRenderer
ItemInteraction
ItemInventory
ItemRepository
ItemNetwork

The exact names and structure must follow the existing project conventions.

6. Architecture Must Be Technology-Agnostic

These rules apply to every type of software project.

Game Development

Architecture should separate independent gameplay responsibilities.

A gameplay entity should not automatically become responsible for:

• Rendering
• Input
• Persistence
• Networking
• UI
• Audio
• Inventory
• Spawning
• Global state

Split responsibilities when they become independent.

Backend

A service must remain focused on one coherent business responsibility.

If a service starts accumulating unrelated responsibilities, separate them into appropriate services or modules.

For example:

OrderService
├── order creation
├── payment processing
├── email delivery
├── analytics
├── inventory management
└── external integrations

This is a warning sign.

The architecture should instead separate independent responsibilities when the project requirements justify it.

Do not introduce microservices merely because a service is large.

Use the architecture that best represents the actual functionality.

Frontend

Separate UI presentation from independent logic when appropriate.

A screen should not become a dumping ground for:

• UI rendering
• API communication
• business logic
• state management
• data transformation
• navigation
• persistence

Use the architecture already established by the project.

For example, depending on the technology:

Screen
Component
State
Logic
Repository
Model

Do not introduce these layers automatically.

Only create them when the project's architecture and task authorize them.

7. Do Not Over-Engineer

The goal is functional architecture, not maximum abstraction.

Do not create abstractions just because they are theoretically possible.

Avoid unnecessary:

• Interfaces
• Wrappers
• Factories
• Managers
• Generic utilities
• Base classes
• Dependency layers
• Design patterns
• Helper classes

Every abstraction must have a real architectural purpose.

Prefer:

simple + focused + functional

over:

abstract + generic + unnecessarily complex

8. Code Must Be Self-Explanatory

Code must be understandable by reading the code itself.

Comments are forbidden.

Do not add:

// Create item
// Check if user exists
// Update inventory

Instead, use expressive names and clear structure.

Bad:

x
data
manager
helper
process
handle
temp
obj

Good:

item
inventory
user
payment
order
selectedItem
availableItems

Names must communicate intent.

9. Language Rules

All code must be written in English.

This includes:

• Variables
• Functions
• Classes
• Interfaces
• Types
• Enums
• Objects
• Properties
• Files
• Directories
• Internal identifiers
• Architecture names

User-facing text may use another language.

For example, this is valid:

const buttonLabel = "Comprar";

But this is invalid:

const textoBotao = "Comprar";

The rule is:

Internal code is English. User-facing content may use the project's required language.

10. Coding Style

Follow the existing project's style whenever it is available.

Do not introduce a different coding philosophy into an existing project.

The preferred style is:

• Explicit
• Typed
• Flat
• Focused
• Readable
• Predictable
• Performance-conscious
• Low nesting
• Low branching
• Small responsibilities

11. Minimize if / else

Avoid unnecessary conditional branching.

Prefer structures that naturally express the desired behavior.

if and else are acceptable when they are genuinely necessary.

Example of an acceptable case:

if (isVisible) {
    showContent()
} else {
    hideContent()
}

This is especially acceptable when the framework or UI architecture naturally requires conditional rendering.

Do not eliminate conditionals at the cost of making the code harder to understand.

The objective is less unnecessary branching, not zero if statements.

12. Minimize Nesting

Avoid deeply nested logic.

Prefer early exits, extracted responsibilities, and flatter structures.

Bad:

if (...) {
    if (...) {
        if (...) {
            if (...) {
                if (...) {
                    execute()
                }
            }
        }
    }
}

Prefer a flatter structure when possible.

A nesting depth of approximately five levels is the maximum acceptable limit.

Even below that limit, reduce nesting whenever doing so improves readability.

Framework-required nesting is acceptable.

For example, declarative UI structures may naturally require nested components.

13. Line Length

Avoid excessively long lines.

Long lines reduce readability and make code harder to scan.

Prefer formatting that keeps related information visually organized.

Do not sacrifice readability merely to reduce the number of lines.

14. Strong Typing

Use explicit and strong typing whenever the language and project support it.

Prefer:

Item[]

over:

any

Prefer precise domain types over generic structures.

Avoid unnecessary use of:

any
dynamic
object
unknown
untyped maps

when a precise type can reasonably be defined.

Do not weaken typing merely to make implementation faster.

15. Performance

Code should be reasonably optimized.

Performance matters, but optimization must remain proportional to the problem.

Prefer data structures according to their actual access patterns.

For example, if the system manages a large amount of indexed data and access is primarily based on numeric IDs, a contiguous array-based structure may be preferable to a hash-based structure.

Consider:

• Memory usage
• Allocation frequency
• Lookup patterns
• Iteration performance
• Data locality
• Serialization cost
• Object creation
• Network overhead
• Rendering cost
• Garbage collection

Do not perform extreme micro-optimizations without a real reason.

The rule is:

Do not write unnecessarily slow code when a simple, equally readable and more efficient implementation exists.

16. Do Not Optimize Outside the Task

Performance improvements must remain within the requested functionality.

Never rewrite unrelated systems simply because they could theoretically be faster.

The task has a defined scope.

Stay inside that scope.

17. No Unrequested Refactoring

Do not refactor code that is unrelated to the requested task.

Do not:

• Rename unrelated classes.
• Reorganize unrelated files.
• Change unrelated APIs.
• Replace working implementations.
• Introduce a new architecture without authorization.
• "Clean up" unrelated code.
• Upgrade dependencies.
• Change configuration.
• Change formatting across unrelated files.

A technically better implementation is still invalid if it exceeds the authorized scope.

18. Preserve Existing Architecture

Before implementing a task, understand the architecture represented by the provided files.

Extend the existing architecture when possible.

Do not replace the architecture simply because another architecture is personally preferred.

If the existing architecture is insufficient to implement the requested functionality:

1. Determine what is missing.
2. Check whether the required files or directories are authorized.
3. If they are not authorized, stop.
4. Report the missing authorization/context.
5. Wait for explicit instructions.

19. Functional Completeness

Generated code must be functional.

Do not generate:

• Placeholder implementations
• Fake repositories
• Dummy services
• Empty methods
• Unnecessary TODOs
• Mock behavior presented as real behavior
• Architecture that looks correct but does not actually work

If the task asks for functionality, implement the actual functionality that can be supported by the provided context.

If the available context is insufficient:

FAIL INSTEAD OF INVENTING MISSING IMPLEMENTATIONS.

20. Do Not Guess

Never assume:

• File locations
• Class names
• APIs
• Framework behavior
• Database schemas
• Existing services
• Existing components
• Dependencies
• Naming conventions
• Business rules
• Network contracts
• Data models

If something is unknown and required, request the missing context.

A wrong assumption is worse than stopping the task.

21. Task Execution Protocol

Before modifying or creating anything, perform this internal validation:

Step 1 — Identify Scope

Determine exactly what the task requests.

Step 2 — Identify Authorized Files

Determine which provided files may be modified.

Step 3 — Identify Required New Files

Determine whether the task requires new files.

Step 4 — Validate Authorization

Verify that every new file has an explicitly authorized location.

Step 5 — Validate Context

Verify that all dependencies required to implement the task are present in the provided context.

Step 6 — Validate Architecture

Determine where the requested functionality belongs according to the existing architecture.

Step 7 — Implement

Implement only the requested functionality.

Step 8 — Validate

Check:

• Correctness
• Types
• Architecture
• Responsibility boundaries
• Nesting
• Unnecessary branching
• Performance
• Naming
• Language
• Scope

Step 9 — Stop

Do not continue improving the project after the requested task is complete.

22. Failure Conditions

The agent MUST stop and report the missing context when any of the following occurs:

• A required file was not provided.
• A required directory was not authorized.
• A required dependency is unknown.
• A required API contract is missing.
• A required business rule is undefined.
• The requested architecture cannot be determined from the available context.
• Implementing the task would require unauthorized changes.
• Implementing the task would require guessing.

The agent must not bypass these conditions by inventing architecture.

23. Priority Order

When making implementation decisions, follow this priority:

1. Explicit user instructions
2. Task scope
3. Provided project context
4. Existing project architecture
5. Functional correctness
6. Single responsibility
7. Type safety
8. Readability
9. Performance
10. Personal architectural preferences

Never sacrifice explicit instructions for personal preference.

24. Final Rule

The agent must always remember:

Do not change what was not authorized.

Do not create what was not authorized.

Do not use what was not provided.

Do not guess what is missing.

Every file must have a clear responsibility.

Every generated solution must be functional.

Keep architecture focused on functionality, not arbitrary file size.

Keep code readable, strongly typed, reasonably optimized, flat, and self-explanatory.

If the required context or authorization is missing, stop and ask instead of improvising.