Refine Python pattern boundaries and Pydantic guidance

This commit is contained in:
Rodin
2026-06-02 00:53:38 +00:00
parent 60ffec18e4
commit 7007b73099
6 changed files with 273 additions and 83 deletions
+11 -17
View File
@@ -45,6 +45,7 @@ Selection criteria:
- `sources/` = raw evidence notes, one file per upstream repo
- `patterns/` = synthesized guidance from repeated evidence
- `comparison/` = short notes for places where a library or framework bends the generic Python rule
- `smells/` = anti-patterns derived from the same evidence base
## Step-by-step workflow
@@ -68,6 +69,8 @@ Important: source notes are not polished guidance. They are reusable evidence.
### 4) Synthesize only after evidence exists
Turn strong repeated signals into `patterns/*.md` docs.
Use `comparison/*.md` only when the generic Python rule still matters, but a specific library or framework changes how it should be applied.
Each pattern doc should usually include:
- what the pattern is
- why it exists
@@ -95,16 +98,17 @@ Instead:
- rewrite source-note files to be denser and more reusable
- reduce duplicated guidance across docs
That was the right move for this repo after the first bootstrap wave.
## Handling mixed-concern source code
## Fresh-context refinement pattern
Upstream code will often mix generic Python design with framework-specific behavior in the same function, block, or line.
A good refinement split is:
- one fresh pass over `patterns/*.md`
- one fresh pass over `sources/*.md`
- one fresh pass doing citation audit and anti-vagueness cleanup
When that happens:
- do not classify the whole snippet by repo name or file path alone
- split the evidence into **Python-level signal** and **framework-owned signal**
- keep only the reusable language/library-design lesson in `python-patterns`
- move the framework-owned lesson into the framework repo or comparison note
The point is to avoid simply echoing earlier wording.
If the claim depends on request parsing, dependency injection, response modeling, or HTTP error semantics, it no longer belongs here as a base Python rule.
## Review checklist
@@ -129,16 +133,6 @@ When the repo is ready for human review:
This repo intentionally avoids pushing or creating remotes unless explicitly requested.
## How to repeat this process next time
1. Define the scope split first.
2. Pick a small, high-signal upstream set.
3. Build `sources/` before `patterns/`.
4. Synthesize only the strongest topics first.
5. Add smell docs after positive patterns exist.
6. Run a fresh-context refinement wave.
7. Initialize git only once the repo is reviewable.
## What to avoid
- writing docs from memory