mirror of
https://github.com/seaweedfs/seaweedfs.git
synced 2026-08-15 19:56:39 +00:00
pingqiuandClaude Opus 4.6
46faf0f7e3
Execution-closure targets: - P1: TransferFullBase — reuse rebuild.go TCP protocol - P2: TransferSnapshot — checkpoint image + WAL tail - P3: TruncateWAL — AdvanceTail + superblock update - P4: Runtime ownership — V2 orchestrator drives execution Key reuse sources identified: - rebuild.go: rebuildFullExtent (client), RebuildServer (server) - wal_writer.go: AdvanceTail - flusher.go: updateSuperblockCheckpoint - blockvol.go: ScanWALEntries (already wired) Slice order: full-base first (highest value), then snapshot, then truncation, then runtime ownership. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
330 lines
7.1 KiB
Markdown
330 lines
7.1 KiB
Markdown
# Agent Development Process
|
|
|
|
Date: 2026-03-30
|
|
Status: active
|
|
Purpose: define the working split between `sw`, `tester`, and review/management roles so each phase and slice has a clear delivery path
|
|
|
|
## Why This Exists
|
|
|
|
The project is now beyond pure exploration.
|
|
|
|
The expensive part is no longer only writing code.
|
|
The expensive part is:
|
|
|
|
1. delivery
|
|
2. review
|
|
3. fixes
|
|
4. re-review
|
|
|
|
So the process must reduce repeated full-stack review and make each role responsible for a distinct layer.
|
|
|
|
## Roles
|
|
|
|
### `manager`
|
|
|
|
Primary role:
|
|
|
|
- phase/plan owner
|
|
|
|
Responsibilities:
|
|
|
|
1. define the phase/slice direction and scope
|
|
2. accept the planning package before coding starts
|
|
3. decide whether a carry-forward is acceptable or must become a gate
|
|
4. perform the final round review for overall logic, omissions, and product-path fit
|
|
|
|
### `architect`
|
|
|
|
Primary role:
|
|
|
|
- plan and technical reviewer
|
|
|
|
Responsibilities:
|
|
|
|
1. review the plan before implementation starts
|
|
2. tighten algorithm wording, scope edges, and expectation framing
|
|
3. review technical correctness during implementation
|
|
4. review API/state/resource/fail-closed behavior
|
|
5. catch semantic drift, scope drift, and V1/V1.5 leakage
|
|
|
|
### `sw`
|
|
|
|
Primary role:
|
|
|
|
- implementation owner
|
|
|
|
Responsibilities:
|
|
|
|
1. implement the accepted slice
|
|
2. state changed contracts
|
|
3. state fail-closed handling
|
|
4. state resources acquired/released
|
|
5. state carry-forward items
|
|
6. add or update tests
|
|
|
|
### `tester`
|
|
|
|
Primary role:
|
|
|
|
- evidence owner
|
|
|
|
Responsibilities:
|
|
|
|
1. define what the slice must prove before implementation starts
|
|
2. maintain the failure-class checklist
|
|
3. define reject conditions and required test level
|
|
4. confirm that implementation claims are actually covered by evidence
|
|
|
|
## Default Routine
|
|
|
|
Each slice should follow this order:
|
|
|
|
1. `manager` defines the plan direction
|
|
2. `architect` reviews and tightens the plan / algorithm / expectation framing
|
|
3. `tester` writes the expectation template
|
|
4. `manager` accepts the package and records it in the phase docs
|
|
5. `sw` implements and submits with the delivery template
|
|
6. `architect` reviews the technical layer until clean enough
|
|
7. `tester` performs validation and evidence closure
|
|
8. `manager` performs round-two review for overall logic and omissions
|
|
|
|
Urgent exception:
|
|
|
|
- if early work already shows major scope drift, protocol contradiction, or V1/V1.5 leakage, architecture review may short-circuit before implementation grows further
|
|
|
|
## Delivery Template For `sw`
|
|
|
|
Each delivery should include:
|
|
|
|
1. changed contracts
|
|
2. fail-closed handling added
|
|
3. resources acquired/released
|
|
4. test inventory
|
|
5. known carry-forward notes
|
|
6. reuse note:
|
|
- files updated in place
|
|
- files used as references only
|
|
- files copied and why
|
|
|
|
This template is required between:
|
|
|
|
1. implementation
|
|
2. implementation/fail-closed review
|
|
|
|
It should accompany the delivery before reviewers start detailed review.
|
|
|
|
Suggested format:
|
|
|
|
```md
|
|
Changed contracts:
|
|
- ...
|
|
|
|
Fail-closed handling:
|
|
- ...
|
|
|
|
Resources acquired/released:
|
|
- ...
|
|
|
|
Test inventory:
|
|
- ...
|
|
|
|
Carry-forward notes:
|
|
- ...
|
|
|
|
Reuse note:
|
|
- ...
|
|
```
|
|
|
|
## Phase Doc Usage
|
|
|
|
Use the three phase documents differently:
|
|
|
|
### `phase-xx.md`
|
|
|
|
Use for:
|
|
|
|
1. current execution direction
|
|
2. current scope
|
|
3. current guardrails
|
|
4. current accepted status
|
|
5. current assignments
|
|
|
|
Keep it short and execution-oriented.
|
|
|
|
### `phase-xx-log.md`
|
|
|
|
Use for:
|
|
|
|
1. detailed planning evolution
|
|
2. review feedback
|
|
3. carry-forward discussion
|
|
4. open observations
|
|
5. why wording or scope changed
|
|
6. slice-level reuse instructions:
|
|
- `update in place`
|
|
- `reference only`
|
|
- `copy is allowed`
|
|
|
|
This document may be longer and more detailed.
|
|
|
|
### `phase-xx-decisions.md`
|
|
|
|
Use for:
|
|
|
|
1. durable phase-level decisions
|
|
2. accepted boundaries that later rounds should inherit
|
|
3. gate decisions
|
|
4. decisions that should not be re-argued without new evidence
|
|
|
|
This document should stay compact and hold only the more important global decisions.
|
|
|
|
## Expectation Template For `tester`
|
|
|
|
Before or at slice start, `tester` should define:
|
|
|
|
1. must-pass expectations
|
|
2. failure-class checklist
|
|
3. required test level for each behavior
|
|
4. reject conditions
|
|
|
|
`tester` should re-engage after technical review is mostly clean, to confirm final evidence closure before the manager's second-round review.
|
|
|
|
Suggested format:
|
|
|
|
```md
|
|
Expectation:
|
|
- ...
|
|
|
|
Required level:
|
|
- entry path / engine / unit
|
|
|
|
Reject if:
|
|
- ...
|
|
|
|
Failure classes covered:
|
|
- ...
|
|
```
|
|
|
|
## Review Checklist For `architect`
|
|
|
|
Review these first:
|
|
|
|
1. nil handling
|
|
2. missing-resource handling
|
|
3. wrong-state / wrong-kind rejection
|
|
4. stale ID / stale authority rejection
|
|
5. resource pin / release symmetry
|
|
6. plan/execute/complete argument correctness
|
|
7. fail-closed cleanup on partial failure
|
|
|
|
## Failure-Class Checklist
|
|
|
|
This checklist should be kept active across phases.
|
|
|
|
Minimum recurring classes:
|
|
|
|
1. changed-address restart
|
|
2. stale epoch / stale session
|
|
3. missing resource pin
|
|
4. cleanup after failed plan
|
|
5. replay range mis-derived
|
|
6. false trusted-base selection
|
|
7. truncation missing but completion attempted
|
|
8. bounded catch-up not escalating
|
|
|
|
## Process Rules
|
|
|
|
### Rule 1: Do not wait until the end to define proof
|
|
|
|
Each slice should begin with a statement of:
|
|
|
|
1. what must be proven
|
|
2. which failure classes must stay closed
|
|
|
|
### Rule 2: Do not let convenience wrappers silently become model truth
|
|
|
|
Any convenience flow must be explicitly classified as:
|
|
|
|
1. test-only convenience
|
|
2. stepwise engine task
|
|
3. planner/executor split
|
|
|
|
### Rule 3: Prefer evidence quality over object growth
|
|
|
|
New work should preferentially improve:
|
|
|
|
1. traceability
|
|
2. diagnosability
|
|
3. failure-class closure
|
|
4. adapter contracts
|
|
|
|
not just add:
|
|
|
|
1. more structs
|
|
2. more states
|
|
3. more helper APIs
|
|
|
|
### Rule 4: Use V1 as validation source, not architecture template
|
|
|
|
Use:
|
|
|
|
1. `learn/projects/sw-block/`
|
|
2. `weed/storage/block*`
|
|
|
|
for:
|
|
|
|
1. constraints
|
|
2. failure gates
|
|
3. implementation reality
|
|
|
|
Do not use them as the default V2 architecture template.
|
|
|
|
### Rule 5: Reuse reality, not inherited semantics
|
|
|
|
When later implementation reuses existing `Seaweed` / `V1` paths:
|
|
|
|
1. reuse control-plane reality
|
|
2. reuse storage/runtime reality
|
|
3. reuse execution mechanisms
|
|
|
|
but do not silently inherit:
|
|
|
|
1. address-shaped identity
|
|
2. old recovery classification semantics
|
|
3. old committed-truth assumptions
|
|
4. old failover authority assumptions
|
|
|
|
Any such reuse should be reviewed explicitly as:
|
|
|
|
1. safe reuse
|
|
2. reuse with explicit boundary
|
|
3. temporary carry-forward
|
|
4. hard gate before later phases
|
|
|
|
### Rule 6: Every substantial slice should declare reuse instructions
|
|
|
|
Before implementation grows, the slice package should state:
|
|
|
|
1. which existing files are expected to be updated in place
|
|
2. which existing files are reference-only
|
|
3. whether any copying is allowed and why
|
|
|
|
This helps prevent:
|
|
|
|
1. accidental scope growth
|
|
2. unclear ownership of old files
|
|
3. hidden semantic inheritance from V1/V1.5 paths
|
|
|
|
## Current Direction
|
|
|
|
The project has moved from exploration-heavy work to evidence-first engine work.
|
|
|
|
From `Phase 06` onward, the default is:
|
|
|
|
1. plan first
|
|
2. review plan before coding
|
|
3. implement
|
|
4. review technical layer
|
|
5. close evidence
|
|
6. do final manager review
|