michele
2f2e35e802
Copy CODING_CONSTITUTION.md from the AgentStore docs/development path and split the seven always-on .mdc files from that exact text.
210 lines
3.9 KiB
Plaintext
210 lines
3.9 KiB
Plaintext
---
|
||
alwaysApply: true
|
||
---
|
||
|
||
## PURPOSE
|
||
|
||
This document defines the mandatory engineering rules for the Periscope project.
|
||
|
||
These rules are not suggestions.
|
||
|
||
They define:
|
||
|
||
* repository structure;
|
||
* coding standards;
|
||
* architectural principles;
|
||
* semantic modeling rules;
|
||
* Python/Rust language policy;
|
||
* testing requirements;
|
||
* verification requirements;
|
||
* Git workflow;
|
||
* commit/push/deployment policy;
|
||
* development-phase discipline.
|
||
|
||
Cursor must treat these rules as **mandatory project constraints**.
|
||
|
||
If an implementation conflicts with these rules, the implementation must be changed.
|
||
|
||
Do not silently relax, bypass, reinterpret, or ignore these rules.
|
||
|
||
---
|
||
|
||
# 1. CREATE THE PROJECT RULE STRUCTURE
|
||
|
||
Create and maintain the following structure:
|
||
|
||
```text
|
||
.cursor/
|
||
└── rules/
|
||
├── 00-coding-constitution.mdc
|
||
├── 10-architecture.mdc
|
||
├── 20-python.mdc
|
||
├── 30-rust.mdc
|
||
├── 40-testing.mdc
|
||
├── 50-verification.mdc
|
||
└── 60-git-workflow.mdc
|
||
|
||
docs/
|
||
└── development/
|
||
└── CODING_CONSTITUTION.md
|
||
```
|
||
|
||
The Markdown document is the human-readable master document.
|
||
|
||
The `.mdc` files are the operational Cursor rules.
|
||
|
||
The rules must be version-controlled with the project.
|
||
|
||
Do not create contradictory rules in different files.
|
||
|
||
If a conflict exists, resolve the conflict explicitly before continuing development.
|
||
|
||
---
|
||
|
||
# 2. CORE PRINCIPLE
|
||
|
||
## CODE THAT FITS IN YOUR HEAD
|
||
|
||
This is the fundamental Periscope engineering principle.
|
||
|
||
> Code must be locally understandable by an engineer without requiring reconstruction of a large hidden abstraction system.
|
||
|
||
Prefer:
|
||
|
||
* small modules;
|
||
* small functions;
|
||
* one responsibility;
|
||
* explicit dependencies;
|
||
* explicit data flow;
|
||
* simple data structures;
|
||
* precise names;
|
||
* deterministic behavior;
|
||
* minimal public APIs;
|
||
* composition over inheritance.
|
||
|
||
Avoid:
|
||
|
||
* huge functions;
|
||
* god classes;
|
||
* deep inheritance;
|
||
* speculative abstractions;
|
||
* hidden state;
|
||
* magic behavior;
|
||
* global mutable state;
|
||
* unnecessary frameworks;
|
||
* premature optimization;
|
||
* unnecessary indirection.
|
||
|
||
A function around 40–60 lines is a warning signal, not an absolute limit.
|
||
|
||
The actual rule is local comprehensibility.
|
||
|
||
A 20-line function can violate the rule if it contains too many responsibilities.
|
||
|
||
A longer function may be acceptable if its structure remains obvious and justified.
|
||
|
||
---
|
||
|
||
# 3. ONE RESPONSIBILITY
|
||
|
||
Every function and module must have one primary responsibility.
|
||
|
||
Prefer:
|
||
|
||
```text
|
||
parse
|
||
↓
|
||
normalize
|
||
↓
|
||
build model
|
||
↓
|
||
analyze
|
||
↓
|
||
produce finding
|
||
↓
|
||
report
|
||
```
|
||
|
||
Avoid a single function that:
|
||
|
||
* parses input;
|
||
* modifies the model;
|
||
* performs analysis;
|
||
* accesses external services;
|
||
* formats output;
|
||
* writes files;
|
||
* handles errors;
|
||
* and generates reports.
|
||
|
||
Separate responsibilities.
|
||
|
||
---
|
||
|
||
# 4. EXPLICIT DATA FLOW
|
||
|
||
Periscope must have explicit data flow.
|
||
|
||
Prefer:
|
||
|
||
```text
|
||
SOURCE
|
||
↓
|
||
PARSER
|
||
↓
|
||
NORMALIZED MODEL
|
||
↓
|
||
ANALYZER
|
||
↓
|
||
FINDING
|
||
↓
|
||
REPORT
|
||
```
|
||
|
||
Avoid hidden communication through:
|
||
|
||
* global variables;
|
||
* singleton state;
|
||
* implicit registries;
|
||
* hidden caches;
|
||
* ambient configuration;
|
||
* side effects;
|
||
* undocumented environment state.
|
||
|
||
If a function needs important information, that information must be visible in its inputs or clearly owned state.
|
||
|
||
---
|
||
|
||
# 5. NO SPECULATIVE ABSTRACTION
|
||
|
||
Do not introduce an abstraction merely because it might become useful later.
|
||
|
||
Do not create unnecessary:
|
||
|
||
* factories;
|
||
* generic managers;
|
||
* service layers;
|
||
* repository layers;
|
||
* plugin systems;
|
||
* inheritance hierarchies;
|
||
* generic object wrappers;
|
||
* framework-like internal infrastructure.
|
||
|
||
Implement the actual requirement first.
|
||
|
||
Abstract only when there is a concrete and demonstrated reason.
|
||
|
||
---
|
||
|
||
# 6. COMPOSITION OVER INHERITANCE
|
||
|
||
Prefer composition.
|
||
|
||
Avoid deep class hierarchies.
|
||
|
||
Inheritance must have a clear semantic reason.
|
||
|
||
Do not use inheritance merely to share a few methods.
|
||
|
||
---
|
||
|