Development
guidelines

How to use this standard

Apply the relevant rules to new work and the areas you change. Assess existing debt separately; this document does not authorize a wholesale rewrite. Choose the smallest design that makes the behavior clear, correct, and verifiable.

• MUST marks an applicable baseline requirement. A conflicting project requirement needs an explicit resolution, not a silent exception.
• SHOULD marks the usual choice. Record a reason when a material departure improves the project.
• MAY marks an optional technique. A listed pattern is not permission to add an unrequested feature.
• Scope comes first. Follow the current task and applicable repository instructions. These house rules do not override higher-priority platform instructions or explicit user decisions. Resolve material conflicts before the affected action; continue independent authorized work.
• Read-only means read-only. In an audit, collect evidence and recommendations. Do not edit application code, install packages, run migrations, restart services, or deploy. Local reports and isolated checks may be appropriate within the authorized scope.
• Publication is separate. This standard does not grant permission to publish, change production, manage accounts, or send messages. Use authorization already provided by the user; do not add approval steps for routine work already authorized.

For a reproducible task, use a versioned edition, read the full applicable sections, and state the version used. A link alone does not load its contents into an AI session. If access is unavailable, request a local copy rather than claiming to have read it.

Architecture and modularization

• ARCH-01 · Give each responsibility a home. MUST. Organize around recognizable product features. Keep entry-point wiring, interaction handling, business rules, storage, and external integrations distinguishable. A route, window, or component should not become the entire application.
• ARCH-02 · Make boundaries real. MUST. Define inputs, outputs, dependencies, state ownership, and side effects. Moving pieces of one giant function into separate files or partial classes does not by itself reduce coupling.
• ARCH-03 · Prefer useful simplicity. SHOULD. Extract a module for a cohesive rule, repeated policy, external dependency, lifecycle, or test boundary. Avoid speculative frameworks, generic utilities that collect unrelated code, and mandatory layers around trivial operations. Microservices are not a default solution to a large file.
• ARCH-04 · Keep shared policy consistent. MUST. Centralize genuinely shared authorization, validation, configuration, and external-client behavior. Keep intentionally different business policies distinct. Do not force superficially similar workflows into one abstraction.
• ARCH-05 · Own state and lifecycle explicitly. MUST. Identify request, session, process, persisted, and disposable state. Keep imports free of unexpected startup work. Define who creates and disposes of processes, streams, timers, locks, connections, and temporary files.
• ARCH-06 · Refactor incrementally. MUST. Protect important behavior before extraction. Move one complete feature at a time, preserve its contract, and verify it. A behavior change, migration, or dependency upgrade must be identified separately from structural cleanup.

A useful dependency direction is interaction → application operation → domain rule or storage/integration boundary. Use the language and framework's idioms; do not create empty layers to reproduce a diagram. File length is a review signal, never an automatic pass/fail threshold.

Readability, naming, and comments

• READ-01 · Write for the next reader. MUST. Use meaningful domain names and consistent terminology. Short indices are fine in small loops; product concepts should not require decoding abbreviations. Follow language conventions and avoid compressing independent operations onto one line.
• READ-02 · Make names truthful. MUST. A mock must not secretly contact production. A read operation must not silently migrate data. Distinguish live providers, demo fixtures, previews, saved results, and published artifacts in names and behavior.
• READ-03 · Keep control flow legible. SHOULD. Use guard clauses where they clarify the main path. Break long expressions and mixed-language templates into understandable units. Prefer ordinary composition over clever indirection.
• READ-04 · Explain reasons beside the code. SHOULD. Comments explain constraints, invariants, compatibility, or deliberate failure policies. Use short adjacent comments when possible. Keep a longer docstring or block when a public contract or algorithm genuinely requires it.
• READ-05 · Keep comments accurate. MUST. Update comments with behavior. Remove obsolete instructions, decorative banners, obvious narration, and debugging stories. Move extended rationale to a short design note. Do not impose a comment-per-function quota.
• READ-06 · Keep diffs focused. SHOULD. Use the existing formatter and conventions. Avoid unrelated mass formatting or cosmetic renaming during a functional change. Do not rename persisted keys or API fields merely to improve internal style.

An example of a useful comment:

// Keep the first assignment; retries must not overwrite an earlier decision.
if (assignments.has(customerId)) return;

Contracts, configuration, and failures

• CON-01 · Identify external contracts. MUST. Document API shapes, serialized keys, environment variables, command-line flags, role behavior, file formats, and version conventions. Make compatibility changes intentional and explain migration needs.
• CON-02 · Load configuration deliberately. MUST. Define precedence and validate required values. Distinguish missing, empty, invalid, inherited, and explicitly overridden values. Use project-relative or injected paths instead of personal machine paths. Local development must not silently select production data.
• CON-03 · Report outcomes truthfully. MUST. Pending is not saved; generated is not delivered; unavailable is not zero. Do not silently replace live data with demo data or report success after a required write fails.
• CON-04 · Define recovery. MUST. Specify success, partial completion, timeout, cancellation, retry, and cleanup for external work. Bound retries and deadlines. Handle expected errors specifically; retain useful diagnostics without leaking secrets.
• CON-05 · Preserve integrity. MUST. Use transactions or equivalent atomic operations for business changes that must succeed together. Handle concurrent edits, duplicate requests, and partial writes deliberately. Make audit failures visible and recoverable.

Ten application security tenets

• SEC-01 · Least privilege and explicit trust. MUST. Use established authentication and cryptographic mechanisms. Give users, services, and credentials only necessary access. Fail closed when required security configuration is missing.
• SEC-02 · Authorization on every protected action. MUST. Check the actor, resource, and action on the server, including ownership, tenant/repository boundaries, downloads, and batch operations. A hidden button or authenticated session is not an authorization policy. Public access must be intentional.
• SEC-03 · Verified identity and attribution. MUST. Derive authoritative actor, owner, and approver fields from verified identity. Do not trust client-supplied names or identity headers outside their defined trust boundary.
• SEC-04 · Validate input at boundaries. MUST. Validate type, shape, size, length, allowed values, pagination, and upload characteristics. Treat files, manifests, remote responses, and model output as untrusted data. Reject malformed input predictably.
• SEC-05 · Safe output and resource access. MUST. Encode for the output context. Restrict URL schemes and destinations where external fetching is allowed. Resolve and validate filesystem boundaries, including symlinks where relevant. Limit file and network access to the intended feature.
• SEC-06 · Safe queries and commands. MUST. Parameterize database values, allowlist dynamic identifiers, and pass subprocess arguments without constructing shell commands from untrusted text. Bound query and process execution.
• SEC-07 · Secret protection. MUST. Keep credentials out of repositories, browser bundles, images, URLs, and logs. Use scoped server-side secret configuration, rotation, and revocation. Examples contain placeholders. Do not build custom encryption schemes.
• SEC-08 · Session lifetime and revocation. MUST. Enforce expiry on the server and define how logout, password reset, account deactivation, and role changes invalidate access. Use appropriate cookies and CSRF protections where applicable; define CORS intentionally. Avoid reusable credentials in query strings.
• SEC-09 · Bounded work and maintained dependencies. MUST. Cap caches with eviction, queues, concurrency, request bodies, expensive actions, and external-call duration. Apply rate limiting where abuse would matter. Use supported runtimes and review dependency advisories and lockfiles.
• SEC-10 · Evidence and recovery. MUST. Log meaningful security events without sensitive payloads, preserve actor attribution, and test access and failure boundaries. Minimize collected personal data, document retention, and support recovery from damaged or incomplete state.

Detailed reference: OWASP authorization guidance. These tenets are a house baseline, not a claim of security certification.

Developer setup and IDE readiness

• DEV-01 · Keep canonical source identifiable. MUST. Document the repository and project root. Include authored source, dependency declarations, applicable lockfiles, and configuration examples. Generated deployment bundles are not a substitute for source.
• DEV-02 · Support a clean local setup. MUST. Document runtime/tool versions, installation, run, debug, test, and check commands. Use synthetic fixtures and disposable data. Explain required external services and available local substitutes.
• DEV-03 · Make editor use practical. SHOULD. Support ordinary VS Code navigation and debugging for suitable stacks, and native Visual Studio solution/project files where appropriate. Add tasks or launch settings when useful. The project must remain manageable through documented commands rather than one editor's hidden state.
• DEV-04 · Make checks consistent. MUST. Provide appropriate formatting, linting, type checking, and behavior-test workflows. A developer should be able to hit a breakpoint in a meaningful operation and run its checks without production credentials.
• DEV-05 · Provide a short source map. SHOULD. Explain entry points, feature locations, shared policies, external dependencies, and state ownership. Include a small domain glossary when useful. A maintainer should not need previous AI conversations to understand the project.

Deployment on a shared VPS

These requirements apply when deployment or operations are in scope. They describe the target pattern; they do not authorize server changes during an audit.

• DEP-01 · Separate environments and privileges. MUST. Keep development, staging where available, and production configurations/data distinct. Isolate project credentials, database access, storage, and runtime identities. Run application work without unnecessary root privileges.
• DEP-02 · Minimize public exposure. MUST. Route public web traffic through the intended HTTPS entry point. Keep internal databases and management interfaces restricted. Review IPv4, IPv6, container publishing, and firewall behavior together. Do not assume a container is a complete security boundary.
• DEP-03 · Use one documented release workflow. MUST. Map a source revision to a reproducible build and identifiable release. Separate build, release configuration, and runtime. Keep secrets and persistent data outside replaceable release files; do not patch production as the source of truth.
• DEP-04 · Identify releases immutably. MUST. Record the commit, version, artifact/image identity, configuration requirements, and migration version. A mutable latest tag alone is insufficient. Retain the prior usable release according to a stated retention policy.
• DEP-05 · Plan rollback and migrations. MUST. Document health checks, smoke checks, graceful shutdown, restart ownership, and rollback. Treat schema/data rollback separately from application rollback. Test risky migrations against representative disposable data and provide a recovery path.
• DEP-06 · Operate within limits. MUST. Define resource limits, timeouts, log rotation, and actionable monitoring so one project cannot easily exhaust the host. Assign backup responsibility and retention; keep protected copies outside the failure domain and verify restoration separately from backup creation.
• DEP-07 · Keep the pattern proportionate. SHOULD. Use a consistent container or process-supervisor convention appropriate to the stack. Document domains, ports, storage, service ownership, and deployment commands privately. Do not introduce orchestration complexity without a concrete need.

Reference: The Twelve-Factor App: build, release, run. Publishing and rollback must stay within the user's authorized task.

UX and interface patterns

Use the patterns that serve the actual task. House presentation defaults are starting points, not reasons to override an established product design or add features.

• UX-01 · Start with the user's task. MUST. Make the current page, object, scope, and next action understandable. Prefer a dominant work area over a dashboard or card grid added by habit.
• UX-02 · Match screen structure to purpose. SHOULD. Collections help find records; detail pages explain one object; editors expose inputs and results; settings group related choices; utilities bring input/output forward. Separate administration from everyday work where useful.
• UX-03 · Keep navigation and scope clear. MUST. Distinguish global and resource-specific actions. Show the active project/account/resource. Use links for navigation and buttons for actions. Support useful deep links, Back, and an accessible narrow-screen navigation alternative.
• UX-04 · Use restrained, readable hierarchy. SHOULD. Use consistent typography, spacing, components, and semantic color tokens. Do not use color alone for meaning. Light is the house starting theme; offer deliberate dark/system choices only when relevant, and verify all supported themes. Density and branding depend on the product.
• UX-05 · Name actions by their effect. MUST. Distinguish save, preview, publish, export, restore, and delete. Show the version, destination, audience, or record scope when consequential. Do not require confirmation for every ordinary save.
• UX-06 · Write useful interface text. SHOULD. Use plain labels and concise instructions that help a decision or recovery. Keep stack traces, implementation details, and long explanations in appropriate operator/help surfaces. Avoid placeholder-only labels and unexplained icons.
• UX-07 · Make forms recoverable. MUST. Associate labels with inputs, show required formats, validate accessibly, preserve input on failure, and prevent duplicate submission. Show persistent actionable errors and accessible asynchronous feedback. Password/credential values need special handling.
• UX-08 · Make tables usable. SHOULD. Use identifiable rows, units, meaningful sorting, and resizable columns where appropriate. Resolve filtering and CSV-export requirements from existing project decisions; ask only when genuinely undecided and material. Define export and selection scope explicitly. Sort the whole result set, preserve relevant settings across pages, and distinguish no records from no matches.
• UX-09 · Preserve editing context. MUST. Display unsaved, saving, saved, and failed states truthfully. Keep drafts, focus, selection, and scroll position through recoverable updates. Detect conflicts where collaborative editing is supported. Preview must not imply publication.
• UX-10 · Expose progress and partial results honestly. MUST. Model loading, empty, success, error, permission-denied, and unavailable-service states. Long work needs suitable progress, cancellation/retry when supported, and a clear result. Do not invent percentages or claim completion before verification.
• UX-11 · Use dialogs deliberately. SHOULD. Keep a dialog focused on one decision. Manage initial focus, keyboard dismissal where appropriate, and focus return. Use a full page for substantial work. For destructive actions, explain the affected scope and offer undo when practical.
• UX-12 · Connect data to evidence. MUST when presenting data. Identify units, time period, filters, source, and uncertainty. Distinguish missing from zero. Offer a suitable text/table alternative to charts. Make details inspectable without exposing private information.
• UX-13 · Keep AI assistance accountable. MUST when using AI. Distinguish suggestions from accepted changes. Show the scope, evidence, and limitations needed to assess output. Do not treat model text as trusted code, credentials, or authorization to act.
• UX-14 · Implement accessibility. MUST. Use semantic controls, accessible names/states, keyboard operation, visible focus, adequate contrast, zoom/reflow, and appropriate touch targets. Target WCAG 2.2 AA for web work and platform-appropriate accessibility for native apps. Verify actual interactions; an automated scan alone is insufficient.
• UX-15 · Assign scroll ownership. SHOULD. Prefer one vertical scroll owner for a page. Avoid nested scrollers; use sibling editor panes in a non-scrolling shell where necessary. Keep navigation/actions reachable without obscuring content. Section or paginate long collections rather than shrinking essential text; adapt the layout at small sizes and zoom.

Accessibility reference: W3C Understanding WCAG 2.2. This is a quality target, not a certification statement.

Common interaction scenarios

• Settings: identify whether a setting is personal, project-wide, or global; show effective values and save state; distinguish stored from successfully tested configuration.
• Login and recovery: separate signed-out, expired-session, invalid-credential, and service-unavailable states. Preserve recoverable work across reauthentication without exposing it to the wrong account.
• First access and identity: distinguish display name, account identity, and permissions. Enforce required onboarding on the server where it controls access.
• People and permissions: show roles in the correct resource scope; distinguish role assignment from membership and ownership. Explain the effect of revocation. Enforce the same rules in the API.
• Restricted actions: distinguish missing permission from missing prerequisites. Provide useful recovery without revealing protected data.
• Invitations and offboarding: model pending, accepted, expired, revoked, and removed states as applicable. Recheck access on the server and make outstanding-session behavior explicit.
• Integrations and credentials: show connection state, scope, last verification, and actionable failures. Never reveal a stored secret merely to prove it exists.
• Runs, schedules, and notifications: show the time zone, next run, actual status, and result when supported. Keep notification preferences explicit. Do not add background work merely because a pattern exists.

Verification and definition of done

• QA-01 · Verify observable behavior. MUST. Test important business rules, authorization, failure paths, and likely regressions. Use realistic fixtures and temporary data. Tests should not simply restate the implementation or assert arbitrary file lengths/private helper names.
• QA-02 · Match checks to the change. MUST. Run required project checks and relevant tests. UI work needs appropriate interaction, keyboard, viewport, long-content, and theme checks. Compilation alone is not evidence that an interface works. Small documentation changes need review and link checks, not an invented application test suite.
• QA-03 · Keep evidence honest. MUST. Report what passed, failed, was not applicable, or was not tested. Separate known baseline warnings from new problems. Do not claim full coverage or a complete audit from a limited sample.
• QA-04 · Finish the handover. MUST. Explain the outcome, affected contracts, validation, remaining limitations, and whether anything was deployed. Update relevant setup instructions, source maps, examples, and comments.

A change is ready when its intended behavior is clear, the affected responsibilities remain understandable, security and data boundaries are preserved, relevant checks support the result, and another developer can continue from the documentation. Remaining debt is explicit rather than hidden behind a successful build.

Audit and exception format

Auditors collect and explain; implementation remains a separately scoped task. Every finding should include an ID, project/module, category, priority, confidence, exact evidence, observed behavior, impact, recommendation, acceptance criteria, relative effort, dependencies, and limitations. Separate confirmed defects, architectural preferences, and unresolved product-policy questions.

For a material exception, record the rule ID, scope, reason, consequences, compensating measures where relevant, owner, and revisit condition. A developer preference cannot silently waive an explicit user requirement. Existing debt does not authorize unrelated changes. Avoid numeric quality scores that imply precision the evidence does not support.

Versioning and adoption

This public reference uses semantic versions. Version 1.0.0 is the first public-ready edition. The revision date identifies this edition, not a claim that a website has already been deployed.

• MAJOR: changes that break an established contract, tighten mandatory behavior incompatibly, or require a changed adoption policy.
• MINOR: compatible additions, optional patterns, and guidance that preserve existing requirements.
• PATCH: corrections, wording, examples, or links without changing the meaning of requirements.
• Preserve released editions and changelog entries. Do not rewrite an older edition under the same version. Use stable rule IDs; record replacements/deprecations rather than quietly changing their meaning.
• The stable page points to the current edition. Versioned paths identify exact editions. Pin the version for reproducible work and record it in the project source map or task handover.
• Review new editions before adoption; do not silently apply changed requirements halfway through a task. New guidance governs relevant future work, while legacy debt is tracked deliberately.

Instruction for a development session

Copy this instruction and provide the page URL or attach its Markdown edition. Fill in the requested task; do not assume the URL is reachable until publication has been verified.

Read Lucas Vitti's Development Guidelines, version 1.0.0, at:
https://lucas.mat.br/development-guidelines/versions/1.0.0/guidelines.md

Also read the applicable repository instructions and project documentation.
Confirm which edition you actually read and apply the relevant requirements.
If the page is inaccessible, ask for the Markdown copy; do not claim to have read it.
Respect the task's scope and existing authorization. Audit-only tasks remain read-only.
Identify material conflicts or justified exceptions before the affected work.
Keep independent authorized work moving. Do not add features just to satisfy a pattern.
For implementation, preserve contracts, verify relevant behavior, and update the handover.
For an audit, provide evidence-based findings and acceptance criteria without making fixes.

Task: [describe the requested work and constraints]

A repository may keep this reference in its agent-instruction file, along with essential local rules for offline use. A local copy should record its version; never depend solely on a link that the session may be unable to fetch.