michele
2f2e35e802
Copy CODING_CONSTITUTION.md from the AgentStore docs/development path and split the seven always-on .mdc files from that exact text.
246 lines
3.9 KiB
Plaintext
246 lines
3.9 KiB
Plaintext
---
|
|
alwaysApply: true
|
|
---
|
|
|
|
# 37. CORRECTNESS BEFORE PERFORMANCE
|
|
|
|
Priority order:
|
|
|
|
```text
|
|
1. Correctness
|
|
2. Semantic integrity
|
|
3. Determinism
|
|
4. Testability
|
|
5. Readability
|
|
6. Maintainability
|
|
7. Performance
|
|
8. Optimization
|
|
```
|
|
|
|
Performance optimization must not compromise the first six without explicit justification.
|
|
|
|
---
|
|
|
|
# 38. MINIMAL PUBLIC APIs
|
|
|
|
Public APIs must be as small as practical.
|
|
|
|
Do not expose internal implementation details unnecessarily.
|
|
|
|
Prefer explicit interfaces.
|
|
|
|
Avoid API surface growth without a real requirement.
|
|
|
|
---
|
|
|
|
# 39. NO DEAD CODE
|
|
|
|
Remove or explicitly document:
|
|
|
|
* obsolete code;
|
|
* commented-out implementations;
|
|
* unused imports;
|
|
* unused abstractions;
|
|
* obsolete APIs;
|
|
* temporary workarounds.
|
|
|
|
Temporary adapters must be clearly identified and have a removal path.
|
|
|
|
---
|
|
|
|
# 40. COMMENTS
|
|
|
|
Comments should explain:
|
|
|
|
```text
|
|
WHY
|
|
```
|
|
|
|
rather than simply:
|
|
|
|
```text
|
|
WHAT
|
|
```
|
|
|
|
Do not comment obvious code.
|
|
|
|
Do document:
|
|
|
|
* non-obvious engineering decisions;
|
|
* semantic constraints;
|
|
* source-specific behavior;
|
|
* intentional limitations;
|
|
* reasons for unusual algorithms;
|
|
* compatibility constraints.
|
|
|
|
---
|
|
|
|
# 41. CHANGE MINIMIZATION
|
|
|
|
For bug fixes:
|
|
|
|
1. reproduce the problem;
|
|
2. locate root cause;
|
|
3. change the smallest appropriate architectural layer;
|
|
4. add regression test;
|
|
5. run relevant tests;
|
|
6. run full regression;
|
|
7. review the resulting design.
|
|
|
|
Do not combine unrelated refactoring with a bug fix unless necessary.
|
|
|
|
---
|
|
|
|
# 42. NO SPECULATIVE ENGINEERING
|
|
|
|
Do not invent engineering rules.
|
|
|
|
Every rule should be based on one of:
|
|
|
|
```text
|
|
documented requirement
|
|
datasheet/source evidence
|
|
standard
|
|
explicit design intent
|
|
validated engineering inference
|
|
```
|
|
|
|
If evidence is insufficient:
|
|
|
|
```text
|
|
INSUFFICIENT_EVIDENCE
|
|
```
|
|
|
|
---
|
|
|
|
# 43. DESIGN INTENT IS FIRST-CLASS
|
|
|
|
Do not assume that every unusual design decision is an error.
|
|
|
|
Periscope must be able to represent:
|
|
|
|
```text
|
|
INTENTIONAL_DESIGN
|
|
```
|
|
|
|
when the evidence supports that interpretation.
|
|
|
|
The system must distinguish:
|
|
|
|
```text
|
|
actual violation
|
|
intentional design
|
|
engineering observation
|
|
insufficient evidence
|
|
```
|
|
|
|
---
|
|
|
|
# 44. FINDING CATEGORIES
|
|
|
|
Findings may include:
|
|
|
|
```text
|
|
ERROR
|
|
RISK
|
|
REFERENCE_DEVIATION
|
|
ENGINEERING_OBSERVATION
|
|
INTENTIONAL_DESIGN
|
|
INSUFFICIENT_EVIDENCE
|
|
```
|
|
|
|
Do not collapse all deviations into ERROR.
|
|
|
|
Severity and confidence remain independent.
|
|
|
|
---
|
|
|
|
# 45. REVIEW QUESTIONS BEFORE COMPLETING ANY CHANGE
|
|
|
|
Before declaring a change complete, Cursor must verify:
|
|
|
|
```text
|
|
Is the implementation correct?
|
|
|
|
Is the root cause fixed?
|
|
|
|
Is the semantic model correct?
|
|
|
|
Is the data flow explicit?
|
|
|
|
Can the code fit in my head?
|
|
|
|
Is any abstraction unnecessary?
|
|
|
|
Is there hidden state?
|
|
|
|
Are units explicit?
|
|
|
|
Are engineering constants named?
|
|
|
|
Are assumptions distinguished from facts?
|
|
|
|
Are tests strict?
|
|
|
|
Are negative cases tested?
|
|
|
|
Are boundary cases tested?
|
|
|
|
Is insufficient evidence tested?
|
|
|
|
Could this change create a false positive?
|
|
|
|
Could this change suppress a true positive?
|
|
|
|
Is the full regression passing?
|
|
|
|
Is documentation updated?
|
|
|
|
Is the macro-phase actually complete?
|
|
```
|
|
|
|
---
|
|
|
|
# 46. FINAL ENGINEERING PRINCIPLE
|
|
|
|
Periscope must not become a clever software system.
|
|
|
|
It must become a:
|
|
|
|
```text
|
|
CORRECT
|
|
DETERMINISTIC
|
|
SEMANTICALLY ACCURATE
|
|
TESTABLE
|
|
TRACEABLE
|
|
READABLE
|
|
MAINTAINABLE
|
|
ENGINEERING SYSTEM
|
|
```
|
|
|
|
The preferred implementation is the simplest one that satisfies those properties.
|
|
|
|
When two implementations are technically correct, prefer the one with:
|
|
|
|
* fewer abstractions;
|
|
* fewer dependencies;
|
|
* less hidden state;
|
|
* clearer data flow;
|
|
* smaller modules;
|
|
* smaller APIs;
|
|
* easier testing;
|
|
* easier debugging;
|
|
* clearer semantics.
|
|
|
|
The governing principle is:
|
|
|
|
> **CODE THAT FITS IN YOUR HEAD.**
|
|
|
|
And the governing development discipline is:
|
|
|
|
> **NO PHASE IS COMPLETE UNTIL ITS TESTS PROVE IT.**
|
|
|
|
And the governing repository discipline is:
|
|
|
|
> **COMMIT AND PUSH AT THE PHASE BOUNDARY AFTER TESTS; DEPLOY ONLY AFTER A MACRO-PHASE.**
|