307 lines
7.9 KiB
Markdown
307 lines
7.9 KiB
Markdown
# Agent Guidelines for dashboard/
|
|
|
|
These rules apply to the entire dashboard repository.
|
|
They exist to keep architecture stable when humans or AI agents modify code.
|
|
|
|
This repo contains:
|
|
|
|
- A large Next.js App Router application (dashboard)
|
|
- Vendored internal libraries under packages/\*
|
|
- No monorepo tooling assumptions beyond local file dependencies
|
|
|
|
AI agents MUST respect these boundaries.
|
|
|
|
---
|
|
|
|
## 1. Build, Lint & Test Commands
|
|
|
|
### Development
|
|
|
|
```bash
|
|
yarn dev # Start development server with MCP server
|
|
yarn build # Production build (runs prebuild scripts)
|
|
yarn build:static # Static build (includes prebuild)
|
|
yarn start # Start production server
|
|
yarn preview # Build and start production server
|
|
```
|
|
|
|
### Code Quality
|
|
|
|
```bash
|
|
yarn lint # Run ESLint (currently fails under Next 16 CLI; use eslint command below)
|
|
./node_modules/.bin/eslint . --no-eslintrc --config .eslintrc.json --resolve-plugins-relative-to . # Run ESLint directly (ignore parent configs)
|
|
yarn typecheck # TypeScript type checking
|
|
yarn format # Format code with Prettier
|
|
```
|
|
|
|
### Testing
|
|
|
|
```bash
|
|
yarn test # Run unit tests (Vitest)
|
|
yarn test:unit # Run unit tests explicitly
|
|
yarn test:e2e # Run E2E tests (Playwright)
|
|
|
|
# Run a single unit test file
|
|
yarn test path/to/file.test.ts
|
|
yarn test --run path/to/file.test.ts
|
|
|
|
# Run a single Playwright spec
|
|
yarn test:e2e path/to/spec.test.ts
|
|
```
|
|
|
|
---
|
|
|
|
## 2. Release Traceability Default Rule
|
|
|
|
For any change touching CI/CD, image tags, deploy contracts, `/api/ping`, or `validate` behavior:
|
|
|
|
- Treat `skills/release-traceability/SKILL.md` as the default reference before implementation.
|
|
- Prefer release metadata that can be traced from `build` to `deploy` to `validate` without manual injection.
|
|
- Keep the published image reference, runtime version, and validation output aligned.
|
|
- Do not introduce a deploy path that rebuilds images on the target host.
|
|
|
|
When in doubt, follow the skill first and keep the release chain fully auditable end to end.
|
|
|
|
---
|
|
|
|
## 3. Repository Mental Model (Read This First)
|
|
|
|
This repository has **three clearly separated layers**:
|
|
|
|
### A. Application Layer (Next.js App Router)
|
|
|
|
src/app/**, src/components/**, src/lib/**, src/state/**, src/modules/\*\*
|
|
|
|
This is the **only place** where:
|
|
|
|
- Routing exists
|
|
- Global state exists
|
|
- Runtime config is loaded
|
|
- Zustand is allowed
|
|
|
|
### B. Vendored Library Layer
|
|
|
|
packages/neurapress/\*\*
|
|
|
|
This is a **library**, not an application. It may contain:
|
|
|
|
- React components
|
|
- Editor logic
|
|
- Markdown utilities
|
|
- Styles and assets
|
|
|
|
It MUST NOT:
|
|
|
|
- Behave like a Next.js app
|
|
- Depend on dashboard routing or aliases
|
|
- Own global state
|
|
|
|
### C. Build / Runtime Glue
|
|
|
|
scripts/**, config/**, public/\*\*
|
|
|
|
Used for build-time or runtime wiring only.
|
|
|
|
---
|
|
|
|
## 4. Import & Alias Rules (Critical)
|
|
|
|
### Dashboard code (src/\*\*)
|
|
|
|
- Allowed: `import { X } from "@/components/X"`
|
|
- Group imports: React → third-party → local types → local components
|
|
|
|
```ts
|
|
import React, { useEffect } from "react";
|
|
import { Button } from "@radix-ui/react-button";
|
|
import type { User } from "@/types/user";
|
|
import { UserCard } from "@/components/UserCard";
|
|
```
|
|
|
|
### Vendored packages (packages/\*\*)
|
|
|
|
- 🚫 ABSOLUTELY FORBIDDEN: `@/` aliases inside packages
|
|
- ✅ Use relative imports or package exports
|
|
|
|
---
|
|
|
|
## 5. TypeScript & Formatting Rules
|
|
|
|
- Strict mode enabled
|
|
- Use `type` for type definitions, `interface` for object shapes
|
|
- Prefer explicit return types for public APIs
|
|
- Use `const` for variables that won't be reassigned
|
|
- Run Prettier via `yarn format` before finalizing changes
|
|
- Keep functions small; avoid large inline objects in JSX
|
|
|
|
---
|
|
|
|
## 6. Naming Conventions
|
|
|
|
- Components: PascalCase (`UserProfile.tsx`)
|
|
- Files: kebab-case for utilities (`user-utils.ts`), PascalCase for components
|
|
- Variables: camelCase (`userName`)
|
|
- Constants: UPPER_SNAKE_CASE (`API_BASE_URL`)
|
|
- Types: PascalCase with `T` prefix for generic types (`TUser`)
|
|
|
|
---
|
|
|
|
## 7. Error Handling & Logging
|
|
|
|
- Use try/catch for async operations
|
|
- Return Result types or throw errors consistently
|
|
- Log errors with context, never expose stack traces to users
|
|
- Avoid swallowing errors without comment or fallback
|
|
|
|
---
|
|
|
|
## 8. React Patterns
|
|
|
|
- Use `'use client'` directive for client components
|
|
- Prefer function components with hooks
|
|
- Use `React.memo` for expensive components
|
|
- Avoid inline functions in render props
|
|
|
|
---
|
|
|
|
## 9. Global State Rules (Dashboard Only)
|
|
|
|
✅ Zustand is the **only** allowed global state mechanism
|
|
❌ React Context for shared/global state is forbidden
|
|
|
|
Allowed only in: src/state/**, src/app/store/**
|
|
|
|
Rule: If state must survive navigation or be shared → it lives in Zustand.
|
|
|
|
---
|
|
|
|
## 10. URL-Synchronized State
|
|
|
|
Anything involving:
|
|
|
|
- URL ↔ state
|
|
- Editor deep links
|
|
- Shareable views
|
|
|
|
MUST be handled inside Zustand slices.
|
|
|
|
❌ Forbidden:
|
|
|
|
- Parsing URL params inside components
|
|
- Sync logic inside useEffect
|
|
|
|
---
|
|
|
|
## 11. Component State Rules
|
|
|
|
Allowed:
|
|
|
|
- useState for local UI only
|
|
- useEffect for browser-only effects
|
|
- useRef for DOM access
|
|
|
|
Forbidden:
|
|
|
|
- useState for cross-component data
|
|
- Local state mirroring global state
|
|
|
|
---
|
|
|
|
## 12. packages/neurapress Rules (Very Important)
|
|
|
|
packages/neurapress is treated as a vendored internal library.
|
|
|
|
MUST:
|
|
|
|
- Keep its own internal structure
|
|
- Use relative imports or package exports
|
|
- Remain usable outside this repo
|
|
- Export public APIs via: src/index.ts, src/editor/index.ts, src/components/index.ts, src/lib/index.ts
|
|
|
|
MUST NOT:
|
|
|
|
- Assume Next.js App Router context
|
|
- Introduce app/, page.tsx, layout.tsx dependencies into dashboard
|
|
- Introduce Zustand, Context, or global state
|
|
- Depend on dashboard-specific CSS or runtime config
|
|
|
|
---
|
|
|
|
## 13. Testing Guidelines
|
|
|
|
- Unit tests: Vitest with jsdom environment
|
|
- E2E tests: Playwright
|
|
- Test files: `*.test.{ts,tsx}` or `__tests__/**/*`
|
|
- Use `describe`, `it`, `expect` from Vitest
|
|
- Mock external dependencies in test setup
|
|
|
|
---
|
|
|
|
## 14. Environment & Runtime Config
|
|
|
|
- No new environment variables without approval
|
|
- Runtime config must live in: src/config/runtime-service-config\*.yaml
|
|
- Runtime config is hydrated in dashboard only
|
|
- packages/\* must remain config-agnostic
|
|
|
|
---
|
|
|
|
## 15. Cursor / Copilot Rules
|
|
|
|
- No `.cursor/rules/`, `.cursorrules`, or `.github/copilot-instructions.md` found
|
|
|
|
---
|
|
|
|
## 16. TL;DR for AI Agents
|
|
|
|
- dashboard = application
|
|
- packages = libraries
|
|
- Zustand only in dashboard
|
|
- No @/ imports inside packages
|
|
- Never "fix" libraries by polluting the app
|
|
- Always run `yarn lint` and `yarn typecheck` before completing tasks
|
|
- If `yarn lint` fails with "Invalid project directory .../lint" (Next 16 CLI), use `./node_modules/.bin/eslint .` instead
|
|
|
|
---
|
|
|
|
# Agent Operating Rules
|
|
|
|
You are an AI agent working inside this repository.
|
|
|
|
## Role
|
|
|
|
- Act as a senior engineer and automation assistant.
|
|
- Prioritize correctness, minimal changes, and reproducibility.
|
|
- agent.md mirrors AGENTS.md; when in doubt, follow AGENTS.md as the source of truth.
|
|
|
|
## Global Rules
|
|
|
|
- Do not introduce new dependencies unless explicitly requested.
|
|
- Do not change API contracts without explicit instruction.
|
|
- Do not add new environment variables without approval.
|
|
- Keep changes scoped to the request; avoid unrelated refactors.
|
|
- Prefer minimal edits that preserve existing behavior and style.
|
|
|
|
## Repository Constraints (Quick View)
|
|
|
|
- App layer: src/app/**, src/components/**, src/lib/**, src/state/**, src/modules/**
|
|
- Library layer: packages/** (no @/ aliases, no global state)
|
|
- Global state: Zustand only, in src/state/** or src/app/store/**
|
|
- URL-synced state must live in Zustand slices
|
|
|
|
## Testing Policy
|
|
|
|
- Follow mcp/testing.md for minimal verification.
|
|
- Always run the minimal verification after a coherent change-set.
|
|
|
|
## Output Format
|
|
|
|
Always respond with:
|
|
|
|
1. Summary of changes
|
|
2. Commands executed
|
|
3. Result (success/failure)
|
|
4. Next step
|
|
|
|
If these rules conflict with user instructions, ask once for clarification and proceed conservatively.
|