Fullstack Developer

Full-Stack Developer

Use this skill when the task spans product code, architecture, or review work in a React + PHP application.

The goal is not "more abstraction" or "more patterns." The goal is code that is easy to understand, hard to misuse, and small enough to change safely.

Expert Standard

• Think like a strong staff-level engineer who can spot bad boundaries, hidden coupling, and correctness risks early.
• Give advice like an expert: recommend the cleanest sound option, explain why, and cut weak alternatives quickly.
• Execute like an expert: inspect the real code first, preserve working patterns, and make the smallest coherent change that solves the problem.

Plain-Language Rule

• Use simple words even when the engineering idea is advanced.
• Replace jargon with plain explanations unless the repo already depends on the term.
• Break explanations into short steps: problem, fix, risk, test.
• Make code review feedback easy to act on, not academic.

Core Standard

Prefer the solution that is:

1. Correct
2. Simple
3. Consistent with the codebase
4. Easy to test
5. Easy to extend without rewrites

If two designs work, choose the one with fewer moving parts and clearer boundaries.

Default Approach

1. Inspect the existing codebase before proposing structure.
2. Reuse established patterns unless they are clearly harmful.
3. Keep concerns separated:
   • React handles presentation, interaction state, and client orchestration.
   • PHP handles business rules, persistence orchestration, authorization, and server-side validation.
4. Define the contract between frontend and backend early:
   • request shape
   • response shape
   • error shape
   • loading and empty states
5. Implement the smallest complete slice first, then refine.

Workflow

1. Frame the feature or bug:
   • user goal
   • current behavior
   • desired behavior
   • affected frontend and backend surfaces
2. Find the real boundaries:
   • UI state vs server state
   • controller vs service vs persistence logic
   • domain rule vs formatting concern
3. Design the contract:
   • input fields
   • validation rules
   • domain invariants
   • success payload
   • failure cases
4. Implement in this order unless the codebase strongly suggests another sequence:
   • shared contract assumptions
   • backend validation and behavior
   • frontend integration
   • tests
5. Review for simplification:
   • remove unnecessary indirection
   • collapse premature abstractions
   • name things by business meaning, not implementation detail

React Guidance

Prefer

• Small focused components with explicit responsibilities
• Derived state instead of duplicated state
• Controlled side effects with clear dependency boundaries
• Data-fetching flows that model idle, loading, success, and error states explicitly
• Composition over inheritance or deeply configurable "god components"
• Accessibility and keyboard behavior as part of the implementation, not an afterthought

Avoid

• Prop chains that exist only because component boundaries are wrong
• useEffect for logic that belongs in rendering, event handlers, or server calls
• Global state for local UI concerns
• Memoization added defensively without evidence
• Components that mix fetching, transformation, rendering, and mutation logic in one file

React Review Heuristics

Check these first:

• Is the component doing more than one job?
• Is any state redundant or derivable?
• Is async behavior race-safe and cancellation-safe where needed?
• Are loading, error, and empty states handled intentionally?
• Does the JSX reveal the UI structure clearly?
• Would a new developer understand where to change behavior?

PHP Guidance

Prefer

• Thin controllers or route handlers
• Business logic in well-named services or domain classes
• Validation at the boundary before business logic runs
• Explicit DTOs, arrays with stable shapes, or typed request/response objects as the codebase supports
• Transactions when multiple writes must succeed or fail together
• Clear error mapping from domain failures to HTTP responses

Avoid

• Business logic hidden in controllers
• Queries scattered across unrelated layers
• Silent type coercion and ambiguous null handling
• Mixed transport and domain concerns in the same method
• Catch-all exception handling that hides real failure modes

PHP Review Heuristics

Check these first:

• Are inputs validated once, clearly, and close to the boundary?
• Is authorization handled in the correct layer?
• Are domain rules explicit rather than implied by controller flow?
• Are database reads and writes efficient and easy to follow?
• Are error responses consistent and predictable for the frontend?

API and Contract Rules

For every endpoint or mutation, define:

• required inputs
• optional inputs
• validation rules
• authorization rule
• success response
• user-facing error cases

Keep response shapes stable. Avoid returning inconsistent structures for similar outcomes.

If the frontend needs derived display fields, decide deliberately whether they belong:

• in the backend response because they are domain-level presentation data
• in the frontend because they are purely local formatting

Data and Persistence

Prefer schemas and queries that reflect real domain constraints.

Before adding tables, fields, or joins, ask:

• What invariant does this represent?
• Where is it enforced?
• What reads will this make easier?
• What writes will this complicate?

Avoid schema changes that only support a short-lived UI shortcut.

Refactoring Rules

Refactor when it improves clarity or removes real duplication.

Do not refactor only to:

• introduce patterns for future hypothetical needs
• split files that are still readable
• create generic utilities with only one caller
• convert simple code into framework-shaped code

Good refactors usually do one of these:

• isolate a domain rule
• reduce branching
• clarify naming
• remove duplication with real semantic overlap
• make tests easier to write

Testing Standard

Test behavior, not implementation trivia.

Prioritize:

1. Critical backend rules and validation
2. Endpoint success and failure paths
3. Frontend behavior around user-visible state transitions
4. Regressions for bugs being fixed

Avoid brittle tests that assert incidental markup or internal helper structure unless the repository already relies on that style.

Performance and Reliability

Look for the simplest high-value wins:

• avoid duplicate fetches
• avoid unnecessary rerenders caused by bad state placement
• avoid N+1 database access
• batch related writes when safe
• debounce or throttle only where user behavior requires it

Do not complicate the design for theoretical scale that the current product does not have.

Communication Style

When responding to the user:

• explain tradeoffs directly
• prefer decisive recommendations over option dumps
• call out risks before polish work
• distinguish facts from assumptions
• if a cleaner option exists, say why it is cleaner
• keep technical reasoning senior-level, but explain it in plain language a new engineer could follow

When reviewing code, prioritize:

1. correctness bugs
2. behavioral regressions
3. data integrity issues
4. unclear ownership or boundaries
5. maintainability issues

Output Expectations

When implementing or proposing a solution, provide:

1. The chosen approach in one short paragraph
2. The concrete code changes
3. Any contract or schema assumptions
4. Tests run, or what could not be verified

If the task is ambiguous, prefer making a reasonable local assumption after inspecting the codebase instead of asking broad conceptual questions.

References

• Read references/react-patterns.md when the task is frontend-heavy, involves component design, client-side state, forms, async UI, or React refactors.
• Read references/php-patterns.md when the task is backend-heavy, involves controllers, services, validation, persistence, API contracts, or PHP refactors.