225 lines
6.0 KiB
Markdown
225 lines
6.0 KiB
Markdown
# Development Playbook: <KEY> — <short title>
|
|
|
|
Status: draft | approved | in progress | done
|
|
Author: I301710
|
|
Model tier for execution: <opus | sonnet | haiku>
|
|
Transport: <TR number>
|
|
Package: <package>
|
|
|
|
The agent runs the phases in order. Each phase ends with a gate. The agent must
|
|
not start the next phase before the gate passes. If a gate fails twice, the
|
|
agent stops and reports. It does not try a third time.
|
|
|
|
---
|
|
|
|
## 0. Context
|
|
|
|
Business need:
|
|
<two or three sentences. no background prose.>
|
|
|
|
Related objects (known before analysis):
|
|
| Object | Type | Role |
|
|
|---|---|---|
|
|
| ZCL_... | class | ... |
|
|
| ZBR_... | report | ... |
|
|
|
|
Out of scope:
|
|
- <what this change must not touch>
|
|
|
|
---
|
|
|
|
## 1. Analysis
|
|
|
|
Input: section 0.
|
|
|
|
Actions:
|
|
1. Run `sap_object_members` for each object in the table above. Read a method
|
|
body only when a gate needs it: `sap_pull_source` with `element=<name>`.
|
|
2. Run `sap_object_members` on two or three similar objects in the package.
|
|
Record the naming pattern and the framework pattern. Do not read bodies.
|
|
3. Run `sap_usage_references` for each object that changes. Record the call
|
|
chain in the table.
|
|
|
|
Output — fill this table:
|
|
|
|
| Object | Direction | Caller / callee | Risk if changed |
|
|
|---|---|---|---|
|
|
|
|
Gate A:
|
|
- [ ] Every object in scope has a known caller list.
|
|
- [ ] The naming convention is written down, not assumed.
|
|
- [ ] No open question remains that needs a system read.
|
|
|
|
If a gate item fails, the agent asks one question. It does not guess.
|
|
|
|
---
|
|
|
|
## 2. Impact analysis
|
|
|
|
Actions:
|
|
1. List the objects that change behaviour.
|
|
2. List the objects that change signature. A signature change needs a caller
|
|
update list.
|
|
3. List the DDIC and customizing dependencies.
|
|
4. State the effect on existing unit tests.
|
|
|
|
Output:
|
|
|
|
| Change | Type | Downstream effect | Mitigation |
|
|
|---|---|---|---|
|
|
|
|
Gate B:
|
|
- [ ] Every signature change has a complete caller list.
|
|
- [ ] The effect on existing tests is stated for each change.
|
|
- [ ] No change touches an object in the "out of scope" list.
|
|
|
|
---
|
|
|
|
## 3. Object plan
|
|
|
|
### 3.1 Objects to change
|
|
|
|
| Object | Type | Change | Verification |
|
|
|---|---|---|---|
|
|
|
|
### 3.2 Objects to create
|
|
|
|
| Object | Type | Responsibility | Package | Naming rule applied |
|
|
|---|---|---|---|---|
|
|
|
|
Each new object needs one sentence of responsibility. If the sentence needs the
|
|
word "and", split the object.
|
|
|
|
Gate C:
|
|
- [ ] Every object has an exact name. No placeholder names remain.
|
|
- [ ] Every object has one responsibility.
|
|
- [ ] The package and the transport are set for each new object.
|
|
|
|
---
|
|
|
|
## 4. Coding standards
|
|
|
|
The agent applies these rules. It does not restate them in the code.
|
|
|
|
- Clean ABAP naming and structure.
|
|
- No comment that restates what the code does. Keep only comments that explain
|
|
a non-obvious reason.
|
|
- No Given/When/Then comment headers in tests.
|
|
- Method length: keep below 40 statements. Split if longer.
|
|
- No new global variable.
|
|
- Exception classes: use the pattern that section 1 recorded, not a new one.
|
|
- Text elements for user-facing text. No hardcoded literal.
|
|
|
|
Project-specific rules recorded in section 1:
|
|
- <naming pattern>
|
|
- <framework pattern>
|
|
|
|
---
|
|
|
|
## 5. Implementation
|
|
|
|
Actions, in order, for each object in section 3:
|
|
1. Change one method with `sap_push_element` (use `signature` when the
|
|
declaration changes too). Push a full source only for a new object, with
|
|
`sap_push_source` — it runs lock, write, unlock, and activate in one call.
|
|
2. Run `sap_check_object` for the object.
|
|
3. Fix errors before the next object.
|
|
|
|
Rules:
|
|
- One object per step. Do not create several objects and activate them together.
|
|
- Do not change an object that section 3 does not list.
|
|
- If the implementation needs an object that section 3 does not list, stop.
|
|
Return to section 3 and update it first.
|
|
|
|
Gate D:
|
|
- [ ] Every object in section 3 is active.
|
|
- [ ] The syntax check returns no error.
|
|
- [ ] No object outside section 3 changed.
|
|
|
|
---
|
|
|
|
## 6. Unit tests
|
|
|
|
Target coverage: <70% or higher>
|
|
|
|
Actions:
|
|
1. Write tests for each public method that section 3 lists.
|
|
2. Keep the tests free of database access. Use test doubles.
|
|
3. Run ABAP Unit. Record the result.
|
|
|
|
Test cases to cover:
|
|
| Case | Object | Expected result |
|
|
|---|---|---|
|
|
|
|
Gate E:
|
|
- [ ] All tests pass.
|
|
- [ ] Coverage meets the target.
|
|
- [ ] No test needs a database connection.
|
|
|
|
---
|
|
|
|
## 7. ATC
|
|
|
|
Actions:
|
|
1. Run `sap_check_object` with the project ATC variant and `runUnitTest=true`.
|
|
2. Report only priority 1 and priority 2 findings. Group them by check.
|
|
3. Fix each finding, or record why the agent does not fix it.
|
|
|
|
Output:
|
|
|
|
| Check | Priority | Object | Decision |
|
|
|---|---|---|---|
|
|
|
|
Gate F:
|
|
- [ ] No priority 1 finding remains open.
|
|
- [ ] Every open priority 2 finding has a written reason.
|
|
|
|
Stop rule: if the same ATC finding returns after two fix attempts, the agent
|
|
stops and reports the finding. It does not try a third fix.
|
|
|
|
---
|
|
|
|
## 8. Acceptance criteria
|
|
|
|
The change is correct when all of these are true:
|
|
|
|
- [ ] <observable behaviour 1>
|
|
- [ ] <observable behaviour 2>
|
|
- [ ] <negative case: what must not happen>
|
|
|
|
Each criterion must be testable from outside the code. "The code is clean" is
|
|
not a criterion.
|
|
|
|
---
|
|
|
|
## 9. Definition of done
|
|
|
|
- [ ] Gates A to F pass.
|
|
- [ ] All acceptance criteria pass.
|
|
- [ ] The transport holds every changed object and no other object.
|
|
- [ ] The agent produced a change summary: object, type, one line of reason.
|
|
- [ ] Open points are listed, or the list is empty.
|
|
|
|
---
|
|
|
|
## Token rules for the agent
|
|
|
|
- `sap_object_members` before source. `element=` before a class. Read a full
|
|
include only when a gate needs the body, and write the reason into this
|
|
playbook.
|
|
- Ask for a targeted change. Do not rewrite a whole object to fix one method.
|
|
- Do not repeat a read that this playbook already recorded. The tables above
|
|
are the memory.
|
|
- After each phase, keep the tables and drop the raw source from the working
|
|
context.
|
|
- If two attempts at a gate fail, stop. A third attempt costs more than a
|
|
question.
|
|
|
|
## Change summary (agent fills this at the end)
|
|
|
|
| Object | Type | Action | Reason |
|
|
|---|---|---|---|
|
|
|
|
Open points:
|
|
-
|