Refine Python pattern boundaries and Pydantic guidance
This commit is contained in:
+11
-17
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user