Skip to content

Add Cursor rules and agent settings for CLI agents#3

Merged
HumanBean17 merged 2 commits into
masterfrom
cursor/agent-rules-and-settings
May 4, 2026
Merged

Add Cursor rules and agent settings for CLI agents#3
HumanBean17 merged 2 commits into
masterfrom
cursor/agent-rules-and-settings

Conversation

@HumanBean17
Copy link
Copy Markdown
Owner

Summary

Adds Cursor settings to help Cursor CLI agents (and other agentic
tools) navigate this repo correctly without rediscovering the same
invariants on every run.

The repo previously had a single .cursor/rules/breaking-changes.mdc.
This PR keeps it and layers six topic-scoped rule files plus a
top-level AGENTS.md and .cursorignore.

What's added

.cursor/rules/

  • project-overview.mdc (alwaysApply) — high-level map: what
    the bundle is, the file table, the env vars, the module /
    microservice resolution order, and which docs to read before
    non-trivial edits.
  • python-style.mdc (globs **/*.py) — Python 3.11+
    conventions used here: from __future__ import annotations, PEP 604
    unions, dataclasses vs Pydantic, stderr-only diagnostics (stdout is
    the MCP transport), the no-cocoindex-import rule outside the flow
    module, and ruff/pytest tooling.
  • tests-and-fixtures.mdc (globs tests/**) — distilled
    version of tests/README.md's "DO NOT OVERFIT" guidance: invariants
    over exact counts, no fixture-special-casing in production code,
    contract-vs-integration split, gating heavy tests behind
    LANCEDB_MCP_RUN_HEAVY=1.
  • graph-and-ast.mdc (globs ast_java.py,
    build_ast_graph.py, graph_enrich.py, kuzu_queries.py,
    java_ontology.py, related tests)
    — node/edge model, role and
    capability inference order, brownfield consistency rule (one
    collect_annotation_meta_chain walk for both Kuzu and Lance),
    call-graph semantics (anonymous classes, lambdas, this.f1.f2.m()
    chains, receiver scope), and project-root semantics across all three
    index call sites.
  • search-and-ranking.mdc (globs search_lancedb.py,
    java_index_flow_lancedb.py, related tests)
    JavaLanceChunk
    schema invariants, the role-weight table, the symbol-bonus formula
    (overlap / action-verb / type-name), the "weights skipped when
    role= locked" rule, filter modes, and the
    LANCEDB_MCP_DEBUG_CONTEXT debugging flag.
  • mcp-server.mdc (globs server.py, test_mcp_tools.py)
    stdio invariants, the contract that tool descriptions are LLM
    prompts (so updates must propagate to README + _INSTRUCTIONS),
    defaults agents rely on (e.g. trace_flow.follow_calls=true,
    find_callers/find_callees.exclude_external=true), and the steps
    for adding a new tool.
  • agent-workflow.mdc (alwaysApply) — investigate → propose
    (when non-trivial) → implement → validate (ruff + pytest) →
    commit/PR loop, matching the existing branch-naming convention
    (plan/<name>, now also cursor/<topic>) and commit-message style.

Repo root

  • AGENTS.md — flat summary of the hard rules and investigation
    order for tools that don't read .cursor/rules/.
  • .cursorignore — keeps Cursor's context out of regenerable /
    binary noise: lancedb_data/, *.kuzu, __pycache__/, .venv/,
    htmlcov/, etc. Mirrors .gitignore plus a few build artifacts
    inside tests/**/target/ and tests/**/build/.

Why these specific rules

Each rule encodes a fact that an agent would otherwise have to
reconstruct from README.md + CODEBASE_REQUIREMENTS.md (~50 KB of
prose) on every run:

  • The Kuzu-vs-Lance Layer-A consistency rule (single
    collect_annotation_meta_chain walk).
  • The fact that role weights and symbol bonus are skipped when the
    caller locks role=.
  • That capabilities are intentionally type-level only.
  • That print() to stdout breaks the MCP transport.
  • That schema changes require a full reindex + ontology_version
    bump.
  • That tests must assert on invariants, not exact counts from the
    bank-chat fixture.

Out of scope

  • No code changes — only rules, docs, and ignore config.
  • No reindex required.
  • No new env vars or schema columns.

@HumanBean17 HumanBean17 merged commit b3ba255 into master May 4, 2026
@HumanBean17 HumanBean17 deleted the cursor/agent-rules-and-settings branch May 4, 2026 18:19
HumanBean17 added a commit that referenced this pull request May 6, 2026
…ty (#32)

Implements propose merged in #28. Sequences after PR-F1 (#31, merged) and
PR-G1 (#30, merged). Hard rename — no deprecation alias, MCP bundle has
no users yet and breaking changes are explicitly allowed.

Single PR, ~115 LOC, ontology bump 8→9. Single source-of-truth flips at
ast_java.py:91 (role) and ast_java.py:114 (HTTP_CLIENT capability);
VALID_ROLES / VALID_CAPABILITIES are auto-derived so no java_ontology.py
edit needed.

9 new tests in tests/test_client_role_rename.py target ~290 passed,
4 skipped (281 baseline + 9).

Plan delta from propose: test #4 asserts warn-and-drop behaviour
(stderr warning + override silently dropped) matching actual
graph_enrich.py:443-447, 481-486, NOT raised ValueError as the propose's
example suggested.

Out of scope: async role/capability changes (MESSAGE_PRODUCER already
covers Kafka/Rabbit/JMS), auto-promoting RestTemplate/WebClient to
HTTP_CLIENT (brownfield-only opt-in), backwards-compat alias,
RegisterRestClient (followup #3).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant