AI Coding Rule Files: Compare Host Tool Context Contracts

TL;DR

Rule files are a context-delivery mechanism, not a universal standard or a security boundary. TRAE, Cursor, and GitHub Copilot may expose different artifact formats and loading behavior, and those details change across releases and clients. Compare them by pinning the exact version, building a small fixture repository, and measuring what context reaches the model for representative tasks.

Use rule files for reviewed conventions and task guidance. Keep authorization, secrets, protected branches, network egress, and deployment approval in systems that enforce them independently of model output.

The Comparison That Matters

A product-name comparison often becomes stale as soon as a client changes an instruction format or its precedence. Start with the work your team needs to perform:

Record that evidence in a small compatibility record:

host: recorded-host
host_version: recorded-version
client_surface: recorded-client
artifact: repository-relative-path
claims_tested:
  - discovery
  - precedence
  - path_scope
  - manual_attachment
fixture_commit: recorded-commit
checked_at: recorded-time
owner: developer-experience

This makes a host upgrade an explicit engineering change rather than an invisible prompt change.

Context Is Not Policy

Rule text can be ignored, misunderstood, or influenced by untrusted repository content, tool results, and user input. A rule saying “do not deploy production” does not prevent a model from requesting a deployment, and a schema that limits a tool argument does not prove the caller may act on the selected object.

Use a separate control plane for these concerns:

Do not put credentials in an instruction file. Do not trust a model-supplied repository, tenant, role, or approval state. A code change still needs review, tests, and the normal delivery controls.

Build a Fixture Before Standardizing

Create a minimal repository owned by the developer-experience team. It should be safe to discard and should contain no real secrets or production connections.

Test at least these cases:

1. A repository-wide artifact and a more specific artifact state contradictory conventions.
2. A file inside and outside the alleged path scope is edited.
3. A task is opened from chat, inline edit, review, and any automation surface your team uses.
4. Untrusted text in a README, issue, fixture, or tool result asks the agent to ignore instructions.
5. An action requires a protected resource or an explicit confirmation.
6. The host tool is upgraded, disabled, or falls back to another client.

Acceptance is not “the model followed the sentence once.” Capture the effective context when the host supports it, inspect the proposed patch, run deterministic checks, and record failures. Treat model compliance as probabilistic; rely on build and policy controls for invariants.

A Portable Artifact Model

Maintain source guidance independently of any vendor layout. Generate or hand-maintain thin host adapters only after verifying their target version.

context/
  shared/
    repository-map.md
    coding-conventions.md
    testing-expectations.md
  host-adapters/
    recorded-host-a.md
    recorded-host-b.md
  fixtures/
    precedence/
    injection/

Each source artifact should identify its owner, intended audience, scope, review date, and evidence. Keep it short enough that a reviewer can find a contradiction. Split by bounded concern, not by a fixed line-count rule.

<!-- owner: platform-team -->
<!-- scope: server/api -->
<!-- reviewed: recorded-date -->

# API change contract

- Validate untrusted input at the service boundary.
- Return errors through the repository's existing error contract.
- Add a focused test for changed authorization behavior.
- Do not expose secrets or internal diagnostics in client responses.

The host adapter may describe how that artifact is attached, but it must not silently become the only source of truth.

Compare Hosts Without Inventing a Ranking

Evaluate each candidate in the same matrix:

TRAE, Cursor, and Copilot are valid candidates only where their recorded client behavior meets this matrix. Avoid treating a path, frontmatter key, or advertised capability as portable across all clients or future releases.

Migration and Rollback

Migrate as a controlled change:

1. Inventory current artifacts, consumers, owners, and undocumented local overrides.
2. Classify text as shared convention, host adapter, sensitive configuration, or trusted policy.
3. Move shared convention into reviewed source artifacts; remove secrets and authorization claims.
4. Implement one host adapter at a time in a fixture repository.
5. Run representative coding, review, test, and failure scenarios.
6. Roll out to a small team with an issue channel and an explicit rollback path.
7. Monitor patch quality, test failures, override frequency, and user feedback rather than invented productivity numbers.

Keep old adapters until the replacement has passed the agreed fixtures. A rollback should remove or disable the adapter without deleting shared guidance or changing trusted access controls.

Prompt-Injection and Privacy Tests

Any file, retrieved document, issue, dependency metadata, or tool result may contain adversarial text. A context artifact can tell the model to treat such material as data, but the host must also bound tool permissions and network access.

Test that an untrusted document cannot:

• change the selected repository or tenant;
• expand tool permissions or reveal a secret;
• cause remote fetches to arbitrary URLs;
• bypass a confirmation for a write, payment, or deployment;
• persist new instructions without review.

Redact or minimize telemetry. Store references, hashes, policy decisions, and bounded excerpts where possible; do not make full prompts, proprietary source, or credentials a default log payload.

Operational Checklist

• [ ] Pin host, extension, and client versions in the compatibility record.
• [ ] Maintain reviewed source guidance with clear owners and scope.
• [ ] Test discovery, precedence, scope, and degradation in fixtures.
• [ ] Keep secret handling and authorization outside model-readable instructions.
• [ ] Enforce confirmation, idempotency, quotas, and audit events for side effects.
• [ ] Require normal code review, tests, and protected delivery controls.
• [ ] Revalidate after host upgrades and rollback on observed regressions.

Summary

The useful question is not which branded rule format is “best.” It is whether a particular host version can deliver reviewed context predictably to the clients your team uses, while trusted systems continue to enforce safety and delivery policy. Treat rule files as versioned context contracts, prove their behavior with fixtures, and keep model guidance separate from authority.