erhan/abap-playbook-skill
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: ABAP playbook skill

Browse Source
This commit is contained in:
Erhan Keseli
2026-08-23 15:58:41 +02:00
commit 543f2befd9
4 changed files with 625 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

48
README.md Normal file
View File

@@ -0,0 +1,48 @@
# abap-playbook
A Claude Code skill for ABAP development through the
[EPOD ADT MCP Server](https://git.epod.dev/erhan/epod-adt-mcp-updatesite).
The skill runs larger development tasks through a phased playbook:
discovery, plan, user approval, implementation, verification. Each phase is
bound to the token-efficient MCP tools — member lists before source, element
reads and writes instead of full pulls, one combined check call — and each
phase ends with a gate.
Small tasks do not open the playbook. The skill applies process only where
the task creates a new object, changes two or more objects, or must keep
the current behaviour.
## Installation
Copy the skill folder into your Claude Code skills directory:
```
git clone https://git.epod.dev/erhan/abap-playbook.git
cp -r abap-playbook ~/.claude/skills/abap-playbook
```
Requirements: Claude Code with the EPOD ADT MCP Server connected. The skill
uses `sap_object_members`, `sap_pull_source` with `element`,
`sap_push_element`, `sap_push_source`, `sap_check_object`, and
`sap_usage_references`.
## Contents
```
SKILL.md the skill: phases, gates, tool bindings
templates/playbook-template.md the empty playbook a task fills in
```
## The short version of the rules
1. Read structure before source. A full pull needs a written reason.
2. The filled playbook goes to the user before implementation. Always.
3. The object list in the plan is a contract.
4. One combined check call per object, not three.
5. A gate that fails two times stops the work. A third attempt costs more
than a question.
## License
Apache License 2.0. Copyright 2026 Erhan Keseli.

100
SKILL.md Normal file
View File

@@ -0,0 +1,100 @@
---
name: abap-playbook
description: >
Use this skill for ABAP development tasks that run through the EPOD ADT MCP
Server. Trigger it when a task creates a new object, changes two or more
objects, or must keep the current behaviour of an object (a refactoring, a
correction in shared code). Do not trigger it for a small task: one method,
one clear fix, no behaviour risk. The skill runs a phased playbook with
gates, binds each phase to the token-efficient MCP tools, and stops for
user approval before implementation.
---
# ABAP Development Playbook
The playbook has five phases. Each phase ends with a gate. Do not start the
next phase before the gate passes. If a gate fails two times, stop and ask.
A third attempt costs more than a question.
## When to open the playbook
Open it when at least one of these is true:
- The task creates a new repository object.
- The task changes two or more objects.
- The task must keep the current behaviour (refactoring, shared code,
correction reports).
For everything else: work directly. Do not add process to a small task.
## Phase 1 — Discovery
Read structure before source. In this order:
1. `sap_object_members` for each object in scope. Not `sap_pull_source`.
2. For the package pattern: `sap_object_members` on two or three similar
objects. Do not read their bodies.
3. `sap_usage_references` for each object that changes.
4. Read a method body only when a gate needs it:
`sap_pull_source` with `element=<name>`. A full pull needs a written
reason in the playbook.
Record the results in the playbook tables (template:
`templates/playbook-template.md`). The tables are the memory. Do not read
the same object twice.
**Gate A:** every object in scope has a caller list, the naming convention
is written down, and no open question needs a system read.
## Phase 2 — Plan
Fill the template: impact table, object plan, test cases, acceptance
criteria. Every object gets an exact name. Every new object gets one
responsibility sentence. For a refactoring: state how the current behaviour
is captured (a saved result list, a comparison run) before any change.
**Gate B/C:** show the filled playbook to the user and STOP. Do not start
Phase 3 without an explicit approval. This gate is never skipped: if the
playbook is open, the approval is required.
## Phase 3 — Implementation
Rules:
- The object list in the plan is a contract. Do not touch an object that
the plan does not name. If a new object becomes necessary, stop, update
the plan, ask again.
- Change one method: `sap_push_element`. Change a signature and a body:
one `sap_push_element` call with `signature`. Push a full source only for
a new object, with `sap_push_source`.
- One object per step. Verify before the next object.
- Move logic without improving it when the task is a refactoring. A fix
found on the way goes to the open-points list, not into the code.
## Phase 4 — Verification
- `sap_check_object` after each object: syntax, ATC, unit tests in one
call. Do not call the three tools separately.
- Priority 1 findings block the gate. An open priority 2 finding needs a
written reason.
- Stop rule: the same finding after two fix attempts stops the phase.
**Gate D:** all objects active, checks clean or explained, all planned
tests green, no object outside the plan changed.
## Phase 5 — Close
Fill the change summary table: object, action, one line of reason. List the
open points, or state that the list is empty. Confirm the transport holds
the planned objects and nothing else.
## Token rules (always active)
- Keep one session for the task. Do not clear the session between phases.
- Read the part, not the file. `sap_object_members` before source,
`element=` before a class.
- After each phase, keep the tables and drop the raw source from the
working context.
- Give the system, the object, and the scope in every sub-task you
formulate. Do not grep and do not run shell commands against pulled
sources when a tool answers the question.

253
templates/playbook-example.md Normal file
View File

@@ -0,0 +1,253 @@
# Development Playbook: EDOC-REFACT-01 — ZEDOC_REPAIR_REPORT test coverage
Status: draft
Author: I301710
Model tier for execution: sonnet for phases 5 and 6, opus for phases 1 and 2
Transport: <TR number>
Package: <eDocument package>
> All lines marked ASSUMED hold placeholder data. Replace them with system data
> before the agent starts phase 1.
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:
ZEDOC_REPAIR_REPORT has no unit tests. The logic sits in the report and reads
the database directly, so a test needs a system connection. The refactoring
must reach 70% coverage without a change to the behaviour that the user sees.
Related objects (known before analysis):
| Object | Type | Role |
|---|---|---|
| ZEDOC_REPAIR_REPORT | report | selection screen, logic, output — ASSUMED ~1400 lines |
| EDOC_HDR | table | eDocument header — ASSUMED |
| EDOC_STATUS | table | status history — ASSUMED |
| CL_EDOCUMENT | standard class | status change API — ASSUMED |
Out of scope:
- The selection screen fields and their names.
- The ALV output layout.
- Any standard SAP object.
- The repair rules themselves. This change moves logic. It does not correct it.
---
## 1. Analysis
Input: section 0.
Actions:
1. Read the report structure: FORM routines, local classes, global data.
2. Find a similar refactored report in the package. Record the pattern that it
uses for data access and for test doubles.
3. Record which FORM routine reads the database and which one only computes.
Output:
| Object | Direction | Caller / callee | Risk if changed |
|---|---|---|---|
| ZEDOC_REPAIR_REPORT | entry | started by user and by job variant EDOC_REP_D — ASSUMED | job variant breaks if the selection screen changes |
| f_select_documents | callee | reads EDOC_HDR | pure database access, move behind an interface |
| f_determine_repair | callee | called by f_select_documents | pure logic, move to the processor class |
| f_apply_repair | callee | calls CL_EDOCUMENT | write access, move behind an interface |
| f_display | callee | ALV | keep in the report |
Naming pattern found in the package — ASSUMED:
- Classes: `ZCL_EDOC_<area>_<role>`
- Interfaces: `ZIF_EDOC_<area>_<role>`
- Test classes: local `ltcl_<subject>` in the class include
Framework pattern found in the package — ASSUMED:
- Data access sits behind an interface. The production class carries the SELECT.
- Test doubles are local classes in the test include.
- The constructor takes the interface. It defaults to the production class.
Gate A:
- [ ] Every FORM routine has a category: read, write, or compute.
- [ ] The job variant list is complete.
- [ ] The naming convention is written down, not assumed.
---
## 2. Impact analysis
| Change | Type | Downstream effect | Mitigation |
|---|---|---|---|
| Move the logic out of the report | behaviour risk | wrong result if a global variable holds state between FORM routines | list every global variable in phase 1 and pass it as a parameter |
| New interface for the read access | new object | none, the report is the only caller | — |
| New interface for the write access | new object | CL_EDOCUMENT calls move into one class | one place to check for the update task |
| The report keeps the selection screen | none | job variant stays valid | do not rename a selection screen field |
| No existing unit test | none | nothing to break | — |
Known risk: the report may run inside an update task. If the write happens in
`IN UPDATE TASK`, the sequence must not change. Confirm this in phase 1 before
phase 5 starts.
Gate B:
- [ ] Every global variable in the report is listed with its readers.
- [ ] The update task behaviour is confirmed, not assumed.
- [ ] The selection screen stays unchanged.
---
## 3. Object plan
### 3.1 Objects to change
| Object | Type | Change | Verification |
|---|---|---|---|
| ZEDOC_REPAIR_REPORT | report | keep the selection screen, the ALV, and the START-OF-SELECTION shell. Delegate the rest to the processor. | run with the job variant, compare the result list with the result before the change |
### 3.2 Objects to create
| Object | Type | Responsibility | Package | Naming rule applied |
|---|---|---|---|---|
| ZIF_EDOC_REPAIR_DATA | interface | declare the read and write operations for repair data | <package> | ZIF_EDOC_<area>_<role> |
| ZCL_EDOC_REPAIR_DATA | class | run the SELECT and the status update against the database | <package> | ZCL_EDOC_<area>_<role> |
| ZCL_EDOC_REPAIR_PROCESSOR | class | decide which document needs a repair and which repair it needs | <package> | ZCL_EDOC_<area>_<role> |
The processor holds no SELECT. It receives data and returns a decision. This is
the condition that makes a database-free test possible.
Gate C:
- [ ] Every object has an exact name.
- [ ] The processor class has no database access in its plan.
- [ ] 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.
- No Given/When/Then comment headers in tests.
- Method length: keep below 40 statements.
- No new global variable.
- Exception classes: use the package pattern. Do not create a new base class.
- Text elements for user-facing text.
Project-specific rules recorded in section 1:
- Class and interface names follow `Z(CL|IF)_EDOC_<area>_<role>`.
- The constructor takes the data interface and defaults to the production class.
- Test doubles are local classes in the test include.
---
## 5. Implementation
Order:
1. `ZIF_EDOC_REPAIR_DATA` — create, activate, syntax check.
2. `ZCL_EDOC_REPAIR_DATA` — implement the interface with the SELECT and the
update that phase 1 recorded. Activate, syntax check.
3. `ZCL_EDOC_REPAIR_PROCESSOR` — move the compute logic from the FORM routines.
Activate, syntax check.
4. `ZEDOC_REPAIR_REPORT` — replace the FORM bodies with calls to the processor.
Keep the selection screen and the ALV. Activate, syntax check.
Rules:
- One object per step.
- Do not change an object that section 3 does not list.
- If the implementation needs another object, stop and update section 3 first.
- Move the logic. Do not improve it. A behaviour change here breaks the
comparison test in section 8.
Gate D:
- [ ] All four objects are active.
- [ ] The syntax check returns no error.
- [ ] The report holds no SELECT statement.
- [ ] No object outside section 3 changed.
---
## 6. Unit tests
Target coverage: 70% or higher on ZCL_EDOC_REPAIR_PROCESSOR.
Actions:
1. Create a local test double for `ZIF_EDOC_REPAIR_DATA` in the processor test
include.
2. Write the cases below.
3. Run ABAP Unit.
| Case | Object | Expected result |
|---|---|---|
| document with a status that needs a repair | processor | the processor returns the repair action |
| document with a status that needs no repair | processor | the processor returns no action |
| document with a status outside the known set | processor | the processor raises the package exception |
| empty input table | processor | the processor returns an empty result, no exception |
| two documents, one needs a repair | processor | the result holds one entry |
| document already repaired on the same day | processor | the processor returns no action |
Gate E:
- [ ] All tests pass.
- [ ] Coverage on the processor is 70% or higher.
- [ ] No test opens a database connection.
- [ ] The test double holds no SELECT.
---
## 7. ATC
Actions:
1. Run ATC with the project variant on the four objects.
2. Report priority 1 and priority 2 findings, grouped by check.
3. Fix each finding, or record the reason for an open finding.
| Check | Priority | Object | Decision |
|---|---|---|---|
Stop rule: if the same finding returns after two fix attempts, the agent stops
and reports it.
---
## 8. Acceptance criteria
- [ ] The report started with job variant EDOC_REP_D returns the same document
list as before the change. Compare with a saved result list.
- [ ] The status update writes the same records as before, in the same
sequence, and in the same update task mode.
- [ ] The selection screen shows the same fields with the same names.
- [ ] A document with an unknown status raises the package exception. The report
shows the message and does not dump.
- [ ] The ALV layout and the column order stay unchanged.
The first criterion needs a result list from before the change. Save it before
phase 5 starts. Without it the criterion is not testable.
---
## 9. Definition of done
- [ ] Gates A to F pass.
- [ ] All acceptance criteria pass.
- [ ] The transport holds the four objects and no other object.
- [ ] The agent produced a change summary.
- [ ] Open points are listed, or the list is empty.
---
## Token rules for the agent
- Read method signatures and the FORM list before the full report source.
- Read a FORM body only in the step that moves it.
- Do not repeat a read that the tables above already record.
- After each phase, keep the tables and drop the raw source.
- If two attempts at a gate fail, stop.
## Change summary (agent fills this at the end)
| Object | Type | Action | Reason |
|---|---|---|---|
Open points:
-

224
templates/playbook-template.md Normal file
View File

@@ -0,0 +1,224 @@
# 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:
-