Skip to main content
r/windsurf icon

r/windsurf

members
online


Let's share our global rules for agents. Here is mine: Let's share our global rules for agents. Here is mine:

Universal AI Team Rulebook (Project-Agnostic)

A globally reusable operational rule set for AI development teams. No project assumptions. No file paths. Pure principles + universal workflows.

Rule 0 — Quality Over Speed

Take the correct architectural path, never the shortcut.

  • Prefer clean designs over quick fixes

  • Avoid wrappers, shims, indirection unless truly necessary

  • Leave the codebase better than you found it

  • Future teams inherit your decisions — choose debt-free solutions

Good > Fast. Always.

Rule 1 — Single Source of Truth (SSOT)

Every project must define one canonical location for:

  • Plans

  • Architecture documents

  • Team logs

  • Questions

  • Phase definitions

Rule: All planning and coordination must happen in that SSOT location. Never fragment planning across multiple places.

Rule 2 — Team Registration & Identity

Every distinct AI conversation = one team.

Your Team ID

  • Determine highest existing team number

  • Your number = highest + 1

  • Team ID is permanent for the lifetime of the conversation

Your Team File

Create a .teams/TEAM_XXX_<summary>.md log file.

Code Comments

When modifying code:

// TEAM_XXX: Reason for change

This ensures long-term traceability.

Rule 3 — Before Starting Work

Every team must:

  1. Read the main project overview

  2. Read the current active phase

  3. Check recent team logs

  4. Check open questions

  5. Claim a team number and create your team file

  6. Ensure all tests pass before making changes

  7. Only then begin implementation

Rule 4 — Behavioral Regression Protection

Every project must define a baseline output for critical behavior (snapshots, reference outputs, golden files, fixtures, deterministic logs, etc.).

Before modifying any behavior-critical logic:

  1. Run baseline tests — they must pass

  2. Make changes

  3. Re-run baseline tests

  4. If results differ → this is a regression → fix it

Never modify baseline data unless the USER explicitly approves.

Rule 5 — Breaking Changes > Fragile Compatibility

Favor clean breaks over compatibility hacks.

Workflow

  1. Move or rename the type/function

  2. Let the compiler fail

  3. Fix import sites one by one

  4. Remove temporary re-exports or legacy names

If you are writing adapters to “keep old code working,” stop — fix the actual sites.

Rule 6 — No Dead Code

Remove:

  • Unused functions

  • Unused modules

  • Commented-out code

  • “Kept for reference” logic (use git history instead)

The repository must contain only living, active code.

Rule 7 — Modular Refactoring

When splitting large modules:

  • Each module owns its own state

  • Keep fields private — expose intentional APIs

  • Avoid deep relative imports

  • Keep file sizes human-readable (< 1000 lines; < 500 preferred)

  • Organize by responsibility, not convenience

Rule 8 — Ask Questions Early

If ANY of the following occur:

  • A decision is ambiguous

  • Requirements conflict

  • Plans seem incomplete

  • Something feels “off”

Create a question file under .questions/ and ask the USER.

Never guess on major decisions.

Rule 9 — Maximize Context Window

While you still remember the state:

  • Perform as much aligned work as possible

  • Don’t stop mid-task if more progress is obvious

  • Minimize context re-initialization for next teams

If a task grows too large: split it into sub-tasks within your team directory.

Rule 10 — Before Finishing

Every team must:

  1. Update their team file with progress

  2. Ensure project builds

  3. Ensure all tests pass

  4. Ensure baseline (golden) tests pass if applicable

  5. Document remaining problems, blockers, or next steps

  6. Write handoff notes

Handoff Checklist

[ ] Project builds cleanly
[ ] All tests pass
[ ] Behavioral regression tests pass (if applicable)
[ ] Team file updated
[ ] Remaining TODOs documented

Rule 11 — TODO Tracking

Any incomplete work must be:

In Code

TODO(TEAM_XXX): what is missing

In Global TODO List

Add corresponding items with file + line + description.

This guarantees future teams know what remains.

Rule 12 — Universal Quick Reference

Concept Description
SSOT The single place where planning/logs/phases live
Team Files Each team writes logs in .teams/TEAM_XXX_*
Questions .questions/TEAM_XXX_*
Current Phase Defines what teams should be working on
Regression Tests Any project-defined baseline outputs
TODO.md Global tracking of incomplete tasks

YSK: Codecademy makes coding jobs attainable. Start learning.
Image YSK: Codecademy makes coding jobs attainable. Start learning.