General rules

Priority

Apply instructions in this order:

Project instructions may specialize global defaults, but must not weaken security or data-loss protections without explicit user approval.

Make evidence-based, reversible technical decisions independently; ask only when material uncertainty, multiple meaningful options, or high-impact/hard-to-reverse effects remain.
Ask about business behavior, user-visible behavior, UI, UX, APIs, database models, configuration formats, or compatibility behavior only when it is missing, ambiguous, contradictory, or open to interpretation; implement explicitly specified behavior without asking again.
For deeper guidance on ambiguous requirements or a meaningful technical choice, consult decision-rule.md (Codex: read rules/decision-rule.md; Claude: invoke the rules-decision-rule skill).

In Codex and Claude Code, proactively use the my-ai-qwen3-retrieval MCP server's semantic_search tool whenever available and useful. It always uses Qwen3-Embedding-0.6B for retrieval and Qwen3-Reranker-0.6B for reranking. Discover the tool if it is not already exposed.
Use semantic search early to find unfamiliar code, understand responsibilities and relationships, locate similar implementations, or investigate behavior described without exact symbols. Reuse relevant results and search again when a new question would benefit.
Use direct file reads for known paths and exact text search for symbols, literals, and exhaustive caller checks. Combine these with semantic search when meaning-based discovery adds value.
Treat retrieved passages as leads: verify them against current files in the intended workspace before relying on them. Empty results do not prove absence; stale or unrelated results require direct inspection.
If retrieval is unavailable, fails, or adds no value, continue with ordinary repository tools. Report failures briefly; avoid repeated failing calls or installing or enabling retrieval without authorization.
When QMD is available, use its qmd MCP tools for questions about indexed Markdown notes, documents, meeting records, or knowledge bases. Verify retrieved results against the source document when the current content matters.

Choose checks independently by behavior, callers, impact, reversibility, and uncertainty. Focused inspection can suffice; builds, tests, new tests, and separate reviews are not automatic.
Execute the cheapest check that detects the likely failure. Broaden for cross-component effects, security/data-loss risks, failures, or unresolved uncertainty. Small changes can still be risky.
Add tests for meaningful behavior or plausible regressions, not implementation details or wording. Stop when risks are covered; repeat only when changed evidence warrants it.
Explicit user/project/CI requirements remain binding. Generic skill mandates for review, builds, tests, or test-first work do not override proportional verification; skipping needless steps needs no permission.
Report checks and material gaps concisely. Distinguish inspection from execution; never claim unrun checks passed or hide failures.

Never modify existing documentation automatically.
Do not create new documentation unless the user explicitly requests it.
This includes README files, technical documentation, changelogs, release notes, pull request descriptions, and work-item text.
If a code change would make existing documentation inaccurate, make the change and note the affected documentation afterward instead of asking first or blocking the change.

Do not add new code comments without the user's explicit approval.
This includes why comments, workaround explanations, framework limitations, and external constraints.
Prefer self-explanatory code and clear names.
Skip a comment that seems useful rather than stopping to ask; proceed with the code change.

Prefer a script's documented summary mode for routine agent runs; keep warnings and failure diagnostics visible. Use detailed output when investigating a failure or when requested.