docs(guidelines): Define Structural Dependency Mapping (SDM) convention

This commit is contained in:
2026-05-09 12:56:56 -04:00
parent 7fb5d9d3b0
commit 3267928c26
3 changed files with 22 additions and 4 deletions
+18 -2
View File
@@ -65,6 +65,22 @@ is processed by AI agents, while preserving readability for human review.
- Hard limit: None — let the formatter handle wrapping if needed.
- Rationale: 80-char limits cause excessive line continuations that waste tokens.
## 10. Main Guard
## 11. Structural Dependency Mapping (SDM)
- All executable files should have `if __name__ == "__main__":` calling `main()`.
To assist AI agents in evaluating refactoring impact across dynamic codebases, all major definitions SHOULD include terse SDM tags at the end of their docstrings.
- **Format:** Tags are enclosed in square brackets at the end of the docstring body.
- **For Functions/Methods:** `[C: CallerA, CallerB]` — List of primary internal callers within the codebase.
- **For State Variables:**
- `[M: File:Line, Method]` — List of primary mutation points (where the value is assigned).
- `[U: File]` — Major codepaths of use (where the value is read but not changed).
### Example:
```python
def start_services(self) -> None:
"""
Initialises background threads and MCP servers.
[C: App.run, _cb_load_project]
"""
...
```