菜单
REQUIRED before any MultiCloudJ feature development. Use when adding, implementing, or creating operations, cross-provider behavior, conformance tests, feature-parity work, or service modules across client APIs, abstract drivers, and AWS/GCP/Alibaba implementations.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/salesforce/multicloudj --skill multicloudj-feature-dev命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
正在显示 SKILL.md
| name | multicloudj-feature-dev |
| description | REQUIRED before any MultiCloudJ feature development. Use when adding, implementing, or creating operations, cross-provider behavior, conformance tests, feature-parity work, or service modules across client APIs, abstract drivers, and AWS/GCP/Alibaba implementations. |
Implements a new feature across the multicloudj SDK through structured phases: requirements gathering via user interview, cross-cloud research for semantic uniformity, client/driver API design, provider implementations, unit tests, and conformance tests with WireMock record/replay.
CRITICAL: Each provider implementation (AWS, GCP, Alibaba) is completely independent and must NEVER reference another provider in any way.
Providers are isolated islands that:
AbstractBlobStore, AbstractDocstore)NEVER:
AwsBlobStore importing from blob-gcp)pom.xmlDO:
// AWS implementation
@Override
protected PutObjectResponse doPutObject(PutObjectRequest request) {
// Unlike GCP which uses resumable uploads, AWS uses multipart
// Similar to how AliOss handles large objects
return s3Client.putObject(...);
}
// AWS implementation
@Override
protected PutObjectResponse doPutObject(PutObjectRequest request) {
// S3 automatically handles objects up to 5GB in a single PUT operation
return s3Client.putObject(...);
}
The driver contract and conformance tests ensure all providers behave the same for the end user. Providers achieve this independently, not by copying or comparing with each other.
flowchart TD
A([User request received]) --> B[Phase 1: Interview]
B --> C[Phase 2: Cross-cloud research]
C --> D{Semantic differences?}
D -->|yes| E[Interview user on resolution]
D -->|no| F[Phase 3: API design]
E --> F
F --> G{User approves API?}
G -->|yes| H[Phase 4: Provider implementations]
G -->|revise| F
H --> I[Phase 5: Unit tests]
I --> J[Phase 6: Conformance tests]
J --> K{Run record mode?}
K -->|yes| L[Collect credentials and record]
K -->|later| M[Write abstract IT only]
L --> N[Phase 7: Create PR]
M --> N
N --> O([Done])
Gather requirements before any code. Ask the user:
Do NOT proceed until you have clear answers to at least questions 1-3.
Research how each cloud provider implements this feature natively. For each provider (AWS, GCP, Alibaba):
Present findings to user as a comparison table:
| Aspect | AWS | GCP | Alibaba |
|---|---|---|---|
| API method | s3.putObjectRetention() | storage.objects().update() | oss.setBucketLifecycle() |
| Supports X | Yes | Partial | No |
| Error on Y | 403 | 404 | 400 |
If providers differ, present the user with options:
UnsupportedOperationException where unavailableInterview the user on which approach to take. The goal is semantic uniformity for the end user - they should not need to know which cloud they're running on.
Design the cloud-agnostic API. This involves changes to the -client module:
Create in the client module's appropriate package:
{service}/{service}-client/src/main/java/com/salesforce/multicloudj/{service}/driver/
Follow existing patterns:
Builder inner class@Getter from Lombok where the module already uses itAdd the abstract do* method to the abstract class (e.g., AbstractBlobStore):
protected abstract {ResponseType} do{OperationName}({RequestType} request);
Add the public method to the client class (e.g., BucketClient):
public {ResponseType} {operationName}({RequestType} request) {
return multiCloudJLogger.traceOperation(
"{operationName}",
() -> blobStore.{operationName}(request)
);
}
Add validation rules to the validator class (e.g., BlobStoreValidator) if inputs need validation.
Present the API design to the user for approval before implementing providers.
For each provider (aws, gcp, ali):
do* MethodIn the provider's main class (e.g., AwsBlobStore):
@Override
protected {ResponseType} do{OperationName}({RequestType} request) {
// 1. Transform multicloudj request → provider SDK request
// 2. Call provider SDK
// 3. Transform provider SDK response → multicloudj response
// 4. Handle provider-specific exceptions via getException()
}
In the provider's transformer class (e.g., AwsTransformer):
to{ProviderRequest}({MulticloudRequest}) - converts outgoing requestto{MulticloudResponse}({ProviderResponse}) - converts incoming responseUpdate ErrorCodeMapping (or equivalent) if the new operation introduces new error conditions.
mvn clean install -DskipTests
mvn test -pl {service}/{service}-{provider}
Write unit tests that verify real behavior, not fake coverage.
mvn clean install -DskipTests
mvn test -pl {service}/{service}-aws -Dtest={TestClassName}
mvn test -pl {service}/{service}-gcp -Dtest={TestClassName}
Conformance tests ensure all providers behave identically for the same operation.
Add test methods to the existing abstract IT class in the client module (e.g., AbstractBlobStoreIT):
{service}/{service}-client/src/test/java/.../Abstract{Service}StoreIT.java
Every conformance test must include both positive and negative scenarios:
This ensures all providers handle both success and failure consistently.
Record mode captures real HTTP interactions with the cloud provider.
Ask the user for credentials:
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKENGOOGLE_APPLICATION_CREDENTIALS (path to service account JSON)Only run the specific tests impacted by your change - never record the entire IT suite. This keeps the PR minimal and avoids regenerating unrelated mapping files.
# AWS record - only the new/changed test method
export AWS_ACCESS_KEY_ID="{from_user}"
export AWS_SECRET_ACCESS_KEY="{from_user}"
export AWS_SESSION_TOKEN="{from_user}"
mvn test -pl {service}/{service}-aws -Dtest="{Provider}{Service}StoreIT#{testMethodName}" -Drecord
# GCP record - only the new/changed test method
export GOOGLE_APPLICATION_CREDENTIALS="{path_from_user}"
mvn test -pl {service}/{service}-gcp -Dtest="{Provider}{Service}StoreIT#{testMethodName}" -Drecord
After recording:
src/test/resources/mappings/# No credentials needed - uses recorded WireMock stubs
mvn test -pl {service}/{service}-aws -Dtest="{Provider}{Service}StoreIT#{testMethodName}"
mvn test -pl {service}/{service}-gcp -Dtest="{Provider}{Service}StoreIT#{testMethodName}"
Write the abstract conformance test (it runs for all providers). The Ali-specific IT class extends it just like AWS/GCP, but recording happens on dedicated machines. The IT harness class already exists (e.g., AliBlobStoreIT) — do not attempt to record locally for Ali.
After implementation and testing are complete, create a PR following MultiCloudJ conventions.
# Stage all changes
git add -A
# Create commit with descriptive message
git commit -m "{service}: {brief description of feature}
{Detailed description of what was changed and why}
- Added X to Y
- Updated Z for compatibility
- Tests: {description of tests added}
"
# Push to origin
git push origin {branch-name}
PR Title Format: {service}: {concise description}
Examples:
sts: onboard proxy configurations for sts interfaceblob: add object versioning supportdocstore: implement batch delete with filterspubsub: add dead-letter queue configurationPR Description Template:
## Summary
{1-2 sentence overview of the feature}
## Changes
- Added `{MethodName}` to `{ClassName}`
- Implemented {feature} for AWS, GCP, and Alibaba Cloud
- Added unit tests for {components}
- {If applicable} Added conformance tests with WireMock recording
## API Example
```java
// Show how users will call the new API
{ServiceClient} client = {ServiceClient}.builder("aws")
.withRegion("us-west-2")
.{newMethod}({parameters})
.build();
mvn test -pl {service}/{service}-{provider}
### 7d. Verify PR Checklist
Before submitting, verify:
- [ ] PR title follows `{service}: {description}` format
- [ ] All unit tests pass locally
- [ ] Conformance tests pass (if applicable)
- [ ] Checkstyle passes (Google Java Style)
- [ ] No provider-specific code in `-client` modules
- [ ] Documentation/examples added (if needed)
- [ ] WireMock mappings committed (if recorded)
- [ ] No credentials leaked in mapping files
## File Checklist
For a feature added to an existing service (e.g., blob), you will typically touch:
| Layer | File | Change |
|-------|------|--------|
| Request/Response | `{service}-client/.../driver/{Request}.java` | New file |
| Request/Response | `{service}-client/.../driver/{Response}.java` | New file |
| Abstract driver | `{service}-client/.../driver/Abstract{Store}.java` | Add `do*` method |
| Public API | `{service}-client/.../client/{Client}.java` | Add public method |
| Validator | `{service}-client/.../driver/{Validator}.java` | Add validation (if needed) |
| AWS impl | `{service}-aws/.../Aws{Store}.java` | Implement `do*` |
| AWS transformer | `{service}-aws/.../AwsTransformer.java` | Add conversion methods |
| GCP impl | `{service}-gcp/.../Gcp{Store}.java` | Implement `do*` |
| GCP transformer | `{service}-gcp/.../GcpTransformer.java` | Add conversion methods |
| Ali impl | `{service}-ali/.../Ali{Store}.java` | Implement `do*` |
| Ali transformer | `{service}-ali/.../AliTransformer.java` | Add conversion methods |
| AWS unit test | `{service}-aws/.../{FeatureOrComponent}Test.java` | New or updated |
| GCP unit test | `{service}-gcp/.../{FeatureOrComponent}Test.java` | New or updated |
| Ali unit test | `{service}-ali/.../{FeatureOrComponent}Test.java` | New or updated |
| Conformance test | `{service}-client/.../Abstract{Service}StoreIT.java` | Add test methods |
| AWS IT harness | `{service}-aws/.../Aws{Service}StoreIT.java` | Already exists |
| GCP IT harness | `{service}-gcp/.../Gcp{Service}StoreIT.java` | Already exists |
| Ali IT harness | `{service}-ali/.../Ali{Service}StoreIT.java` | Already exists |
| AWS mappings | `{service}-aws/src/test/resources/mappings/` | Recorded stubs |
| GCP mappings | `{service}-gcp/src/test/resources/mappings/` | Recorded stubs |
## Common Mistakes
- **Adding provider-specific types in client module** - the client module must never import AWS/GCP/Ali SDKs
- **Skipping the user interview** - assumptions about semantics lead to rework
- **Implementing before researching all three clouds** - discovering a provider can't support the feature after implementation is costly
- **Writing conformance tests that are provider-specific** - the abstract IT must work for ALL providers
- **Leaking credentials in WireMock recordings** - always verify mapping files before committing
- **Writing unit tests that only test happy path** - error mapping and edge cases are where bugs hide
- **Not running `mvn clean install -DskipTests` before running individual module tests** - inter-module dependencies need to be built first
- **Manually editing or creating WireMock mapping files** - all mappings must be produced by WireMock recording only. If a recording is stale or corrupt, delete it and re-record.
- **Recording the entire IT suite instead of just the new test** - only run the specific impacted test method in record mode to keep the PR diff minimal
## Red Flags - STOP and Reconsider
- You're implementing a provider without having researched how the other providers handle it
- You're adding a method to the abstract class without a corresponding public client method
- You're writing a conformance test that uses provider-specific setup
- You're importing `software.amazon.awssdk` or `com.google.cloud` in a `-client` module
- You're writing a unit test with no assertions about returned values or thrown exceptions
- You're running record mode without asking the user for credentials first
- You're about to manually edit a WireMock mapping JSON file - STOP: delete and re-record instead
- You're running the full IT class in record mode when only one test method is new/changed - use `#testMethodName` filter
- **You're writing a comment in a provider that references another provider** (e.g., "Unlike GCP", "Similar to AWS") - STOP: providers must be isolated
- **You're importing classes from another provider module** (e.g., `blob-aws` importing from `blob-gcp`) - STOP: providers cannot depend on each other