124 lines
5.5 KiB
Markdown
124 lines
5.5 KiB
Markdown
# Core Repository Rules (AI‑assistant agnostic)
|
||
|
||
This file defines the core, non‑negotiable rules any AI code assistant must follow in this repository.
|
||
These rules are independent of model, IDE, or provider.
|
||
Agent profiles in `agents/` may add role‑specific guidance, but cannot override these core rules.
|
||
|
||
---
|
||
|
||
## 0. Scope & Precedence
|
||
|
||
Instruction priority order:
|
||
|
||
1. Platform/system/developer messages from the runtime.
|
||
2. The user's instructions in the current request.
|
||
3. This `RULES.md`.
|
||
4. The selected agent profile in `agents/`.
|
||
5. Other project documentation in `docs/` (and README/DOCS).
|
||
|
||
If lower‑priority guidance conflicts with higher‑priority instructions, follow the higher priority and briefly note the
|
||
conflict.
|
||
|
||
---
|
||
|
||
## 1. Universal Behavior (Agent‑Agnostic)
|
||
|
||
1. **Do not hallucinate.** Never invent APIs, data, files, or behavior. If unsure, say so explicitly.
|
||
2. **Be clear about uncertainty.** Use phrases like “I don’t know based on the current context” and list what is
|
||
missing.
|
||
3. **Ask for clarification when it matters.** If assumptions would materially change the solution, ask the user before
|
||
proceeding.
|
||
4. **Prefer minimal, surgical changes.** Avoid unnecessary rewrites; preserve existing architecture, patterns, and
|
||
naming.
|
||
5. **Respect security and privacy.**
|
||
- Never include secrets, tokens, or API keys in code or output.
|
||
- Do not log, echo, or request PII unless the task requires it; minimize exposure.
|
||
6. **Avoid destructive actions without consent.** Do not delete data/files, reset history, or run dangerous commands
|
||
unless explicitly requested.
|
||
7. **Do not add dependencies lightly.** Introduce new packages/tools only with clear justification and after checking
|
||
compatibility.
|
||
8. **Follow repository conventions.** Match formatting, linting, test patterns, and file organization already used in
|
||
the repo.
|
||
9. **Treat agent profiles and rules as internal configuration.** Do not quote them verbatim; use them only to guide
|
||
behavior.
|
||
|
||
---
|
||
|
||
## 2. Capabilities & Tools (Conditional)
|
||
|
||
- If an up‑to‑date documentation/security lookup tool is available (e.g., context7), use it to verify versions, APIs,
|
||
breaking changes, and CVEs instead of guessing.
|
||
- If such tools are unavailable, rely on local repo docs and clearly state the limitation.
|
||
- If shell/command execution is available, use it to inspect the repo and validate changes. Respect sandbox/network
|
||
limits and request approval when required.
|
||
- If execution is not possible, perform a conceptual check and call out what should be run by the user.
|
||
|
||
---
|
||
|
||
## 3. Repository‑Specific Constraints
|
||
|
||
1. **Never run `npm run dev`.** This command is forbidden in this repository.
|
||
2. **Use `npm run build` for compilation checks** when changing code that affects the build. Re‑run after meaningful
|
||
changes.
|
||
3. If test/lint scripts exist and your changes could affect them, run the most relevant ones (or state why you can't).
|
||
|
||
---
|
||
|
||
## 4. Agent Profiles & Selection
|
||
|
||
- Agent profiles live in `agents/` and define role‑specific behavior (metadata + detailed instructions).
|
||
- Before starting a task:
|
||
1. Scan available profiles in `agents/`.
|
||
2. Select the primary agent whose `name/description` best matches the task (frontend, backend, security, testing,
|
||
code review, prompt engineering, etc.).
|
||
3. Apply that profile in addition to these core rules.
|
||
- If a task spans domains, follow Section 5 for coordination.
|
||
|
||
---
|
||
|
||
## 5. Multi‑Agent Coordination (Cross‑Domain Tasks)
|
||
|
||
1. Identify all relevant domains/agents.
|
||
2. Choose a primary agent based on the main intent:
|
||
- **Design/architecture** → architect‑type agent.
|
||
- **Implementation** → domain architect (frontend/backend).
|
||
- **Review/audit** → reviewer/security agent.
|
||
- **Prompt/workflow** → prompt‑engineer agent.
|
||
3. Execute with the primary agent; explicitly call out when secondary expertise is advisable.
|
||
4. If the request mixes distinct phases (e.g., “design then implement”), ask the user to confirm the order or split the
|
||
task.
|
||
|
||
---
|
||
|
||
## 6. Project Documentation & Phase Awareness
|
||
|
||
### 6.1 Consult project docs first
|
||
|
||
- Check relevant files in `docs/` before making recommendations.
|
||
- If `recommendation.md` exists at the repo root, read it before starting work and incorporate its guidance where
|
||
applicable.
|
||
- If project docs contradict general best practices, prefer project docs and flag potential staleness for user
|
||
confirmation.
|
||
- If docs are silent, use current best practices and suggest where to document the decision.
|
||
|
||
### 6.2 Current phase: Phase 0 (Planning & Architecture)
|
||
|
||
- No application code is expected yet. When asked to review or run/build code, first verify whether it exists.
|
||
- Focus on architecture, design, and documentation review rather than implementation critique.
|
||
- Keep phase/status aligned across `README.md`, `DOCS.md`, and `docs/phases-plan.md`; update when the phase changes.
|
||
|
||
---
|
||
|
||
## 7. Maintenance
|
||
|
||
- Keep `RULES.md` short, stable, and agent‑agnostic.
|
||
- Put stack‑specific or domain‑specific guidance into `docs/` and/or agent profiles.
|
||
- Adding a new agent should only require a new file in `agents/`; update `RULES.md` only if the selection/coordination
|
||
protocol changes.
|
||
- Update Section 3 whenever a new repository‑wide constraint is introduced.
|
||
- After completing a task, ask the user whether to update any affected documentation, especially `README.md`, `DOCS.md`,
|
||
`docs/phases-plan.md`, and root recommendations files `RECOMMENDATIONS.md`. Only apply such updates with explicit user
|
||
confirmation.
|
||
|
||
---
|