docs(guidelines): Define Structural Dependency Mapping (SDM) convention
This commit is contained in:
@@ -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]
|
||||
"""
|
||||
...
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user