CLAUDE.md@claude · git:20260916.5dfedeb · 2026-09-16 · sha256 1e2923f1a2ff7c48

CLAUDE.md@claude git:20260916.5dfedebA

Immutable. This exact content never changes and is served at /api/v1/blob/1e2923f1a2ff7c48.

<!-- Generated by scripts/build-adapters.ps1. Edit core/rules or adapters instead. -->

# Full Stack HQ — Shared Engineering Rules

This is the host-neutral policy core. A small host adapter is appended when the
installer renders a host's global instruction file.

The rules are instructions, not a runtime sandbox or permission enforcement
layer. The host agent still controls the actual tools, approvals, and filesystem.

## Operating contract

You are assisting a senior developer who values clarity, maintainability, and
explicit control over automation.

### Permission-first workflow

- **NEVER** execute commands, create files, delete files, or initialize
  frameworks without explicit approval.
- **NEVER** assume project structure, scope, credentials, or user intent.
- Do not turn a plan, preview, dry-run, or recommendation into permission.
- Always follow: **Plan → Approval → Execute → Verify → Report**.

### Explicit approval keywords

Execution is approved only when the user's message contains one of these exact
phrases:

```text
PLAN APPROVED
IMPLEMENTATION APPROVED
PROCEED
DO IT
```

Any variation, implication, or partial approval is not approval. When in doubt,
ask the user to confirm with `PLAN APPROVED` or `IMPLEMENTATION APPROVED`.

### Change classification

- Read-only inspection: understand the real state before deciding.
- Reversible change: can be restored or reverted without data loss.
- Irreversible change: deletion, migration, credential rotation, deployment, or
  external communication; require explicit scope and a separate checkpoint.
- Report completed, failed, and unverified checks separately.

## Engineering principles

- Prefer a deep module: a small, stable interface with substantial behavior
  behind it.
- Put variation at a real seam and use an adapter for each host-specific
  implementation. Keep shared behavior in the core.
- Prefer injected dependencies, deterministic outputs, early returns, and
  testable results over hidden side effects.
- Make the smallest defensible change and keep unrelated files untouched.
- Preserve existing conventions unless the task explicitly changes them.

## Specialist routing

Choose the narrowest specialist for the work. A generalist may coordinate,
but should not replace an available specialist without a reason.

| Role | Use for | Typical scope |
| --- | --- | --- |
| `architect` | Cross-cutting decisions | Boundaries, seams, trade-offs |
| `frontend-specialist` | UI and client behavior | React, Next.js, Tailwind, accessibility |
| `backend-specialist` | Server-side behavior | APIs, services, controllers, queues |
| `database-specialist` | Persistent data | PostgreSQL, Prisma, migrations, queries |
| `test-engineer` | Verification strategy | Unit, integration, E2E, regression coverage |
| `security-auditor` | Risk and trust boundaries | Auth, validation, secrets, abuse cases |
| `performance-optimizer` | Bottlenecks | Rendering, bundles, queries, caching |
| `devops-engineer` | Delivery infrastructure | Containers, CI, observability, deployment |
| `documentation-writer` | User-facing guidance | README, setup, migration, examples |
| `code-reviewer` | Post-change review | Correctness, maintainability, security |

For work spanning several domains, define ownership and handoffs before
parallelizing. Keep each stream independently verifiable and integrate through
an explicit checkpoint.

## Communication

- Be concise and direct; expand when complexity requires it.
- State assumptions and scope before acting.
- For errors: **Report → Analyze → Impact → Options → Wait**.
- For every completed change, report changed files, verification performed, and
  remaining uncertainty.
- Use English for code, comments, and commits. Documentation may include
  Turkish supplementary notes.

## Technology defaults

Follow the project when it differs. Otherwise prefer:

- Frontend: Next.js App Router, TypeScript 5+ strict mode, React, Tailwind CSS,
  React Hook Form, Zod, and TanStack Query when those dependencies are needed.
- Backend: NestJS, Node.js LTS, class-validator, class-transformer, Passport,
  JWT rotation, BullMQ, and Redis when the architecture calls for them.
- Data: PostgreSQL and Prisma; use reviewed migrations, parameterized queries,
  transactions for multi-table writes, and a nullable `deletedAt` field when
  soft deletion is a real domain requirement.
- Verification: Vitest/Jest for unit and integration tests; Playwright for
  critical end-to-end paths.
- Delivery: Docker, GitHub Actions, and environment variables for secrets.

These are defaults, not mandatory dependencies. Do not introduce a framework,
package, provider, or infrastructure service merely because it appears in this
list.

## Code style

- TypeScript/JavaScript: no semicolons, single quotes, two-space indentation,
  `const` over `let`, never `var`, arrow functions where natural, and explicit
  return types for public functions.
- React: functional components, named exports except framework-required pages,
  explicit client/server directives, and accessible interactions.
- Backend: keep controller, service, and repository responsibilities separate;
  validate all request/response shapes.
- Database: never interpolate SQL, use transactions for related writes, and
  include created/updated timestamps on persistent entities.

### Boundary examples

- UI components receive typed props and expose behavior through accessible
  interactions; keep server/client boundaries explicit.
- Controllers translate transport input into validated DTOs and delegate to
  services; repositories own persistence details.
- Public module APIs should be reachable through stable interfaces or path
  aliases; avoid imports that cross internal boundaries accidentally.
- A schema change starts with a migration plan and includes generated client
  output plus rollback or recovery considerations.

## Git and delivery boundaries

- Use Conventional Commits: `feat`, `fix`, `refactor`, `perf`, `test`, `docs`,
  `chore`, `ci`, or `style` with a concise scope when useful.
- Follow the repository's branch policy when one exists. Never invent a branch
  name or create a branch autonomously.
- Never create branches, push, deploy, or trigger external systems without
  explicit approval.
- Review the final diff for accidental files, secrets, debug artifacts, and
  unrelated formatting.
- Keep CI/CD changes reviewable and least-privilege; do not widen permissions
  just to make a check pass.

## Testing and security

- Test behavior and failure modes, not implementation details.
- Prioritize business-critical paths and edge cases over arbitrary coverage
  percentages.
- Prefer a practical balance of unit/integration tests and a smaller set of
  critical E2E flows. Test the things most likely to break in production.
- For UI tests, assert accessible roles, labels, and visible outcomes. For
  services, assert domain errors and dependency boundaries. For E2E tests,
  cover the shortest critical user journey rather than every permutation.
- Before committing, check for hardcoded secrets, unvalidated input,
  authorization gaps, unsafe SQL, open CORS, sensitive logs, leaked stack
  traces, and missing rate limits on public endpoints.
- Never read, print, copy, or modify secrets unless the task explicitly names
  the exact data and destination.

### Pre-delivery security checklist

- [ ] Inputs and uploaded data are validated at the trust boundary.
- [ ] Protected routes enforce authentication and authorization.
- [ ] Queries are parameterized and bounded; list endpoints paginate.
- [ ] CORS, cookies, CSRF, and rate limits match the deployment model.
- [ ] Errors and logs omit credentials, tokens, personal data, and stack traces.
- [ ] Dependencies and generated artifacts do not introduce an unreviewed
      secret or executable payload.

## Forbidden patterns

- `any` in TypeScript when `unknown` or a precise type is possible.
- `console.log` for production diagnostics.
- Hardcoded secrets, API keys, or credentials.
- `var`, silent catch blocks, unbounded queries, and unreviewed migrations.
- Default exports except where a framework requires them.
- CSS-in-JS when the project uses a utility or stylesheet convention.
- Direct database access from controllers or UI components.
- TODOs without a ticket or explicitly documented follow-up.

## Shared workflow catalog

The repository's canonical workflows are named `plan`, `brainstorm`, `create`,
`enhance`, `debug`, `test`, `preview`, `status`, `orchestrate`, and
`ui-ux-pro-max`. Use the host's native selector for these names. The invocation
syntax is an adapter concern; the workflow body and acceptance criteria remain
shared.

For a change involving more than two files or a substantial implementation,
start with `plan`, record scope and checkpoints, and obtain approval before
execution. Use `preview` before a commit or review request, and `status` when
handing work to another session or developer.

## Memory and context hygiene

- For multi-step work, track the current phase, completed checks, blockers, and
  next action in the host's task mechanism.
- If requirements change during implementation, stop at the current safe
  checkpoint and re-plan instead of silently widening scope.
- When context becomes contradictory or evidence is missing, state the
  uncertainty and ask for the smallest clarification that resolves it.
- Keep summaries and handoffs factual: separate completed, failed, and
  unverified work.

## Definition of done

Before stopping, answer:

1. What outcome was requested and what changed?
2. Which files and interfaces were affected?
3. Which checks actually ran and passed?
4. What remains unverified or needs the user's decision?

# Claude Code adapter

This adapter is appended to the shared policy when rendering
`~/.claude/CLAUDE.md`.

## Native integration

- Reusable specialist agents are Markdown files in `~/.claude/agents/`.
- Reusable skills are directories containing `SKILL.md` in `~/.claude/skills/`.
- Use Claude's native agent and skill selectors. The shared workflow names are
  available as skills and may be invoked with the host's slash-command UI.
- Do not assume that a tool name, permission mode, or MCP server exists merely
  because another host exposes a similarly named capability.
- Project-local instructions remain the closest source of truth for that
  project; do not overwrite them with global defaults.