菜单
Use when a Spryker project adopts a custom namespace instead of Pyz and the code layer must resolve, build, lint, and test it — namespace registration, composer autoload, frontend build config, codeception wiring. A pre-boot wizard step of project start; skipped entirely when the project keeps Pyz.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/spryker-sdk/ai-dev --skill configure-codebase命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
正在显示 SKILL.md
| name | configure-codebase |
| description | Use when a Spryker project adopts a custom namespace instead of Pyz and the code layer must resolve, build, lint, and test it — namespace registration, composer autoload, frontend build config, codeception wiring. A pre-boot wizard step of project start; skipped entirely when the project keeps Pyz. |
Goal: after this, a class in src/<Ns>/... overrides Pyz/core, a Yves component under src/<Ns>/Yves/*/Theme compiles, and the project has runnable test infrastructure — a committed example test under tests/<Ns>Test/ that codecept build + codecept run prove green (post-boot), not just an empty .gitkeep tree. (Codebase/test failure-signature triage lives in the Known-traps catalog: ../project-starter-wizard/references/pitfalls.md.)
Read .ai-dev/project-setup.md → namespace. If mode: keep-pyz, record the step skipped (keep-Pyz) and stop. Otherwise <Ns> = namespace.name (validated CamelCase, no collision with Pyz/core).
Work from real files; these are judgment edits (each config file has its own idiom), not bulk transforms.
Placement principle — governs the WHOLE project run, not just this step. Once
<Ns>is registered (PROJECT_NAMESPACES = ['<Ns>','Pyz'],<Ns>wins resolution), every project-level PHP customization — config classes, plugins, expanders, dependency providers — is created insrc/<Ns>/…, EXTENDING thePyzclass (or core if no Pyz counterpart exists), andsrc/Pyz/…is left pristine as the inherited demoshop layer. Never edit asrc/Pyzclass in place to customize it when a custom namespace is set — including store-keyed config classes a later step (e.g.define-stores' literal sweep) needs to change. Extend the Pyz class, not core, when a Pyz counterpart exists, or its existing overrides are silently dropped. (keep-pyzmode:src/Pyzis the project layer — edit it directly.) This is the rule the other skills assume; the trap is editing aSalesPaymentMerchant*config insrc/Pyzwhile correctly creatingStockConfig/CheckoutPageConfiginsrc/<Ns>— the same run, two placements.
config/Shared/config_default.php: KernelConstants::PROJECT_NAMESPACE = '<Ns>' (primary), KernelConstants::PROJECT_NAMESPACES = ['<Ns>', 'Pyz'] (resolver order — project wins, Pyz stays as working fallback so the app keeps booting via its literal Pyz\ bootstraps), and the same in GlueBackendApiApplicationConstants::PROJECT_NAMESPACES.
config_default.php and this clone re-assigns GlueBackendApiApplicationConstants::PROJECT_NAMESPACES = ['Pyz'] in config/Shared/config_default-docker.dev.php and config_default-ci.php — i.e. in exactly the environment the first boot runs (deploy.dev.yml → environment: docker.dev) and in CI. Editing only the base file ships a Backend Glue API that silently ignores src/<Ns>. Grep every config/Shared/config_default-*.php for PROJECT_NAMESPACE re-assignments and patch each one to ['<Ns>', 'Pyz'] — the base-file edit alone is not registration.config/Glue/packages/spryker_api_platform.php, config/GlueBackend/packages/spryker_api_platform.php, and config/GlueStorefront/packages/spryker_api_platform.php each call sourceDirectories([...'src/Pyz'...]) — API resources under src/<Ns> are invisible to discovery until 'src/<Ns>' is appended in all three (anchored edit; the array also carries vendor paths — add, never replace).composer.json: autoload.psr-4 add "<Ns>\\": "src/<Ns>/"; autoload-dev.psr-4 add "<Ns>Test\\": "tests/<Ns>Test/". (Autoload dump happens at boot.)src/<Ns>/{Client,Glue,Service,Shared,Yves,Zed}/ with .gitkeep, including src/<Ns>/Zed/Translator/data/ (the project-level Back Office translation location, auto-scanned per project namespace). tests/<Ns>Test/{Zed,Yves,Glue,Shared}/.Namespace registration is complete only when a Grep for PROJECT_NAMESPACE across ALL of config/Shared/config_default*.php (base + every -<env> overlay) shows <Ns> in every assignment — one overlay still assigning ['Pyz'] silently un-registers the namespace in that environment (the docker.dev/ci clobber above). php -l the edited PHP (incl. the seed ExampleCest.php); JSON-validate composer.json/tsconfig*/package.json with php (allowlisted: php -r 'json_decode(file_get_contents("composer.json")); echo json_last_error_msg();') — not node. Only the JS files (frontend/settings.js, *.mjs) need node --check; node isn't in the base allowlist, so either recommend adding node:* or treat the JS syntax-check as optional (it's belt-and-suspenders — the boot's frontend build is the real proof). The codecept build/run green proof for the seed module is post-boot (needs composer install) — carried by boot-and-verify, not here. Update the configure-codebase step; note the eslint backlog follow-up if surfaced.
Test scoping is complete only when BOTH trees are proven in scope — by these greps, not by assertion. Step 4's two mandates (every aggregate config; the projectNamespaces sweep) are the ones runs commonly skip, so verify them rather than assuming them done: an aggregate config left PyzTest-only means <Ns> never runs in that lane (CI runs -c tests/codeception.ci.functional.yml), and an unswept suite stays pinned to ['Pyz']. Both trees must be in scope, and the failure is bidirectional: one direction runs only <Ns>, the other runs only Pyz, and each reports OK while testing half the code. These edits are purely additive — nothing anywhere replaces PyzTest.
# 1. EVERY config the globs match (root + each tests/codeception.*.yml) must show BOTH namespaces in `include`
grep -n 'Test/\*/\*' codeception.yml tests/codeception.*.yml # each file: <Ns>Test AND PyzTest
# 2. and BOTH trees in the coverage whitelist
grep -n "src/.*\*\.php" codeception.yml tests/codeception.*.yml # each file: src/<Ns>/*.php AND src/Pyz/*.php
# 3. no suite may still resolve src/Pyz only
grep -rc "projectNamespaces: \['Pyz'\]" tests/ | grep -v ':0$' # MUST print nothing (total count MUST be 0)
A missing PyzTest in (1)/(2) means you replaced instead of appended; a surviving hit in (3) means those suites test src/Pyz config while the application runs src/<Ns> — green on the wrong values, and the thing a developer describes as "the Pyz tests don't cover my namespace". (static-validation is not involved and needs no edit — its diff script never invokes codeception, has no namespace concept, and excludes PyzTest/<Ns>Test symmetrically.)
Yves component discovery — prove BOTH directions with the custom namespace. POST-boot, like the codecept proof: component discovery reads vendor/. Runs whichever frontend shape (a)/(b)/(c) applied. Registering <Ns> in the settings is not proof; a new component and an override fail differently, so run both:
src/<Ns>/Yves/ShopUi/Theme/default/components/atoms/ns-probe/ns-probe.{twig,scss}, the scss carrying one unique marker (.ns-probe { outline: 1px solid red; }), then docker/sdk console frontend:yves:build (or docker/sdk up --assets). Pass = build OK and grep -rl 'ns-probe' public/Yves/assets/ hits a compiled bundle. Empty grep on a green build = src/<Ns>/Yves never entered the component finder's dirs — the settings registration did not take (re-check shape (a)/(b)/(c) above).vendor/spryker-shop/shop-ui/.../Theme/default/components/molecules/<X>/ into src/<Ns>/Yves/ShopUi/Theme/default/components/molecules/<X>/, change one visible marker in its twig and its scss, rebuild, and load the page. Pass = the marker appears in the rendered HTML and the compiled css — the project namespace outranks the vendor/Pyz copy. Fail = <Ns> is missing or ordered after Pyz in the component dirs; fix the order, not the component.Record the result in the step report; an unrun probe stays an open deferred check, not a "done".
src/<Ns>/**/*.php): add/remove/rename → docker/sdk console cache:class-resolver:build (method-body edits need no rebuild).src/<Ns>/Shared/*/Transfer/*.transfer.xml): transfer:generate → src/Generated/. Propel schema (src/<Ns>/Zed/*/Persistence/Propel/Schema/*.schema.xml): propel:schema:copy → propel:model:build → propel:diff. Both discover src/<Ns> by path glob — no namespace coupling.tests/<Ns>Test/Shared/Example seed (its codeception.yml with namespace: <Ns>Test\... + projectNamespaces: ['<Ns>','Pyz'], actor, cest) → vendor/bin/codecept build → codecept run -c <suite-dir> <Suite>. Never copy a PyzTest config's projectNamespaces: ['Pyz'] verbatim — set ['<Ns>','Pyz'] or the test won't see src/<Ns>..gitkeep skeleton. "Ready to write tests" is not the deliverable; working test infrastructure is (a main requirement). A test only runs when its module has a codeception.yml and the aggregate suite configs include the namespace — a bare skeleton runs nothing. Do all four; the first three are pre-boot file edits, the fourth is verified post-boot:
codeception.yml — add tests/<Ns>Test/*/* to include; add src/<Ns>/*.php to the coverage whitelist.
include and the seed module below are ONE atomic edit — never land an include without at least one tests/<Ns>Test/<Layer>/<Module>/codeception.yml under it. A Symfony Finder glob matching no directory throws, rethrown as ConfigurationException, so an empty-glob include makes codecept unloadable project-wide: nothing runs, neither tree, not even PyzTest. Do not believe the opposite ("globs match nothing until suites exist — harmless"); it is false. Triage signature: Configuration file(s) could not be found in "tests/<Ns>Test/*/*". Same rule for each aggregate config below.ls tests/codeception.*.yml (today codeception.acceptance.yml, codeception.api.yml, codeception.ci.functional.yml — examples of the class, not the whole set; a clone may ship more, and new ones appear as the demoshop evolves). Each ships include: PyzTest/*/* and whitelists src/Pyz/*.php only. Add <Ns>Test/*/* to each include and src/<Ns>/*.php to each whitelist — otherwise codecept run via those suites silently skips <Ns>Test and never covers src/<Ns>. (Patching only the root config leaves them blind.) Leave each file's top-level namespace: PyzTest key untouched — it only namespaces root-level suites (there are none); it is not a resolver setting to "fix".
@group annotations are NOT generated for a project namespace, so the group-filtered lanes stay INERT until you hand-write them. The upstream sniff DocBlockTestGroupAnnotation2Sniff matches #/(tests)/(SprykerTest|PyzTest)/…#, so nothing under tests/<Ns>Test/** ever receives an auto-generated @group. codeception.acceptance.yml (inclusive: [Presentation]) and codeception.api.yml (inclusive: [Glue, EndToEnd]) require all listed groups to be present, so they filter out every un-annotated <Ns>Test test — only codeception.ci.functional.yml (exclusive filters) actually runs them, and a codecept run -g Business never selects a project-namespace test either. Every <Ns>Test cest therefore needs hand-written annotations in the PyzTest shape — @group <Ns>Test, @group <Layer>, @group <Module>, @group <Suite>, @group <Class>. Patch the acceptance/api includes anyway (they cost nothing and pay off the moment annotations exist), but do not report those two lanes as covering <Ns>Test until a cest carries the block.DE project (two places). The core \SprykerTest\Shared\Store\Helper\StoreDependencyHelper hardcodes DEFAULT_STORE = 'DE' and publishes it as the container store service, so on any project whose stores aren't named DE the suites throw StoreNotFoundException: Store with name "DE" not found — deep inside a plugin (e.g. the tax calculator), so it reads as a code bug, not a test-infra defect — before exercising any project code. Fix it with a project-level helper the suites resolve the store from the DB through:
tests/PyzTest/Shared/Store/_support/Helper/StoreDependencyHelper.php, namespace PyzTest\Shared\Store\Helper;, extends the core SprykerStoreDependencyHelper, uses LocatorHelperTrait, and overrides _before() to set SERVICE_STORE to getLocator()->store()->facade()->getCurrentStore(true)->getNameOrFail() (the DB store, whatever the project named it).codeception.yml that enables a store helper — swap - \SprykerTest\Shared\Store\Helper\StoreDependencyHelper → - \PyzTest\Shared\Store\Helper\StoreDependencyHelper in modules.enabled (grep -rl finds them all — every suite config that enables the core helper, however many the clone ships). When you author a new <Ns>Test module suite that needs a store, reference the PROJECT helper, never the core one.grep -rl 'SprykerTest\\Shared\\Store\\Helper\\StoreDependencyHelper' tests/PyzTest --include=codeception.yml finds the suites still on the core helper; then create the helper and repoint them.getCountries(), not reuse the store name as an ISO2 literal, or tax/shipping totals silently drift on a non-DE store.test-autoload.php — add an <Ns>Test branch mirroring the PyzTest branch (same array_shift → tests/<Ns>Test/<app>/<module>/_support/<Class>.php path) so generated actor/support classes autoload. Make the branches mutually exclusive (elseif, or return inside each) — the shipped file uses independent ifs that mutate a shared $classNameParts via array_shift, so a later branch can inspect an already-shifted array; harmless today (no class matches two prefixes) but don't propagate the fall-through into the new branch.tests/<Ns>Test/Shared/Example/, BOTH the green proof and the canonical copy-me template. Its codeception.yml MUST set namespace: <Ns>Test\Shared\Example and, on LocatorHelper, projectNamespaces: ['<Ns>', 'Pyz'] — the PyzTest module configs hardcode ['Pyz']; copying that blind makes a test resolve only src/Pyz and silently never exercise your src/<Ns> overrides (the single most important gotcha). Files:
# tests/<Ns>Test/Shared/Example/codeception.yml
namespace: <Ns>Test\Shared\Example
paths: { tests: ., data: _data, support: _support, output: _output }
coverage:
enabled: true
remote: false
whitelist: { include: ['../../../../src/*'] }
suites:
Example:
path: Example
actor: ExampleTester
modules:
enabled:
- Asserts
- \PyzTest\Shared\Testify\Helper\Environment
- \SprykerTest\Shared\Testify\Helper\LocatorHelper:
projectNamespaces: ['<Ns>', 'Pyz']
composer install the first boot performs; this step runs pre-boot, so vendor/bin/codecept does not exist yet). The run is verified as the tail of the first boot — boot-and-verify runs docker/sdk cli vendor/bin/codecept build then docker/sdk cli "vendor/bin/codecept run -c tests/<Ns>Test/Shared/Example Example" and expects OK. Infrastructure is not "created" until that passes. Every real per-module config a developer later adds copies this seed's namespace + projectNamespaces shape.projectNamespaces: already in tests/ and prepend <Ns>. The inherited PyzTest suite configs pin projectNamespaces: ['Pyz'] (the demoshop's only project namespace). LocatorHelper overwrites the runtime PROJECT_NAMESPACES with the suite's own value, so any suite left on ['Pyz'] resolves src/Pyz and silently never exercises your src/<Ns> overrides — those suites then test different config than the application runs (nothing fails; the resolver finds the Pyz parent and the suite goes green on the wrong values). grep -rln "projectNamespaces" tests/ and set each to ['<Ns>', 'Pyz'] (project namespace first = highest precedence), the same value the seed models. This CAN move test outcomes, so apply it deliberately and re-run — don't fold it into an unrelated edit.tests/<Ns>Test/, never tests/PyzTest/ — the same rule already applied to src/<Ns>/. The namespace exists so project code stays separable from the inherited demoshop layer; a helper written into tests/PyzTest/** sits in the merge path the next time that tree re-syncs from upstream. Decide by "is this project-authored?", not by which tree the triggering file happens to live in. Seed tests/<Ns>Test/Shared/ (not only Zed/Glue/Yves) so the right destination isn't an empty dir that reads as unused. Closing check: find tests/PyzTest -newer composer.json — anything this run authored there is misfiled.frontend/settings.js with a projectNamespaces array — add ./src/<Ns>/Yves to it (component finder + stylelint scan both spread it). (b) frontend/settings.js with NO projectNamespaces (a single paths.project = './src/Pyz/Yves' string, and the finder dirs arrays spread paths.project individually) — additively append join(context, './src/<Ns>/Yves') to the componentEntryPoints.dirs and shopUiEntryPoints.dirs arrays (leave paths.project as-is; you're adding a second dir, not replacing). (c) NO frontend/settings.js at all — the Yves builder is vendorized. Decide the branch on a fact you can test, not on how recent the clone is: ls frontend/settings.js frontend/yves.settings.mts plus the ShopUi version (composer show spryker-shop/shop-ui, or the spryker-shop/shop-ui constraint in composer.json). From ShopUi 2.0.0 the builder moved into vendor/spryker-shop/shop-ui/**/FrontendBuilder/build.mts (+ libs/lint/stylelint.mts), the project-level settings file became frontend/yves.settings.mts, the yves:* npm scripts were re-pointed at that builder, and the toolchain needs Node 24+. So on (c): if frontend/yves.settings.mts exists, register <Ns> there — same additive component-dir shape as (b), never replacing the Pyz entry. If it is absent too, the component-dir resolution lives only under vendor/, which does not exist pre-boot, so it is uninspectable here — record this half as a post-boot verification in the step report — once vendor/ exists, read the FrontendBuilder's component-dir resolution and run the add/override probe in § Verify. Reporting the step done without either the settings edit or that deferred check recorded is the failure mode. (Optional aside: if the spryker-upgrade skill happens to be installed, its EXAMPLE-UPGRADE-REPORT.md records the same move — but do not depend on it being there; everything needed is above.) Match the file's real structure — don't force the projectNamespaces shape onto a file that doesn't use it. tsconfig.base.json / tsconfig.yves.json: add ./src/<Ns>/Yves/**/* to the include array (and the Zed path in tsconfig.base.json). Leave tsconfig.yves.json's compilerOptions.paths unchanged — the per-module aliases (src/ShopUi/*, src/CompanyWidget/*, src/ConfigurableBundleWidget/*, src/ProductImageWidget/*) stay pointed at ./src/Pyz/Yves/<Module>/Theme/default/* only. Do not prepend ./src/<Ns>/Yves/... to them: the frontend build resolves each alias to its first entry, so with src/<Ns>/Yves still an empty skeleton at this point, every src/ShopUi/* and ~src/ShopUi/* import resolves to an empty directory and frontend:yves:build aborts. The namespace's Yves components are wired through the componentEntryPoints.dirs/shopUiEntryPoints.dirs additions in the settings file (above — frontend/settings.js, or frontend/yves.settings.mts in shape (c)), not through these aliases. package.json: extend yves:lint/yves:lint:fix globs to ./src/{Pyz,<Ns>}/Yves/... — read the script bodies first: under ShopUi 2.0 the yves:* scripts are re-pointed at the vendorized builder, so the glob edit may not apply at all. (These tsconfig.*/package.json edits are the pre-boot half and stay in scope in all three shapes, including (c).) frontend/libs/stylelint.mjs: verify its real scss-path source — if it derives from projectNamespaces, shape (a) covers <Ns>; if it derives from paths.project or its own dirs list (shape b), add <Ns> there the same additive way. Leave the Merchant Portal Angular app-shell (angular.json, tsconfig.mp.json) Pyz-anchored — no new theme.phpcs.xml) — make the namespace-aware sniffs know <Ns>. <file>src/</file> already scans src/<Ns>/, so the general sniffs cover the custom namespace with no path edit. Two namespace-specific points:
Spryker.MethodAnnotation.* rules (Factory / Config / Facade / Repository / EntityManager / QueryContainer) carry a <property name="namespaces" type="string" value="Pyz,SprykerEco,…"/> comma-list that tells the sniff where to find and annotate those classes. If the clone's phpcs.xml has them, add <Ns> to each list (anchored edit to the string, e.g. value="<Ns>,Pyz,SprykerEco,…") so the project's *Factory/*Config/*Facade/… get correct @method annotations validated.Spryker.Namespaces.SprykerNamespace namespace="Pyz" as-is — that property names the base bootstrap namespace (Pyz stays in PROJECT_NAMESPACES as the resolver fallback); the custom namespace belongs in the MethodAnnotation lists above, not here. Don't switch it to <Ns>.phpcs.xml with no MethodAnnotation.* rules at all (only SprykerNamespace); then there is nothing to extend. If the project wants @method annotation checks on its custom-namespace classes, add the six rules following the same pattern; otherwise flag it as an optional follow-up and move on — it is not a boot or build blocker. Apply the same grep-for-Pyz-and-add-<Ns> check to any other lint/analysis config that hardcodes a namespace list (phpstan.neon, architecture rulesets).eslint.config.mjs — the Yves-TS block's files glob is a vendor-package path shape that matches no project code (Pyz included), so project Yves .ts is silently unlinted. Add 'src/{Pyz,<Ns>}/Yves/**/*.ts' to that block's files. The fix can't be validated pre-boot (node_modules doesn't exist until the first boot), and it surfaces a pre-existing violation backlog in existing Pyz Yves TS — so record it as an explicit post-boot gate with a named rollback (revert that one glob line) rather than a vague follow-up: the failure lands in the js-validation CI job the developer didn't touch, so without the rollback named it reads as an unrelated breakage.src/. Optional; flag rather than assume.DEconsoleMissing setup for store: <STORE>SPRYKER_DYNAMIC_STORE_MODE: trueproject-ci-generator$i->assertX()PHPUnit\Framework\Assert::$iAssert::assertTrue(true)$icode:sniff:style<?php // tests/<Ns>Test/Shared/Example/Example/ExampleCest.php
declare(strict_types = 1);
namespace <Ns>Test\Shared\Example\Example;
use <Ns>Test\Shared\Example\ExampleTester;
class ExampleCest
{
public function testCustomNamespaceTestInfrastructureIsRunnable(ExampleTester $i): void
{
$i->assertTrue(true);
}
}
assertTrue(true)Config::get(KernelConstants::PROJECT_NAMESPACES)LocatorHelperprojectNamespaces:<Ns>config_default.php<?php // tests/<Ns>Test/Shared/Example/Example/ProjectNamespaceCest.php
declare(strict_types = 1);
namespace <Ns>Test\Shared\Example\Example;
use <Ns>Test\Shared\Example\ExampleTester;
class ProjectNamespaceCest
{
public function testComposerAutoloadsTheProjectNamespace(ExampleTester $i): void
{
$composer = json_decode((string)file_get_contents(APPLICATION_ROOT_DIR . '/composer.json'), true);
$i->assertSame('src/<Ns>/', $composer['autoload']['psr-4']['<Ns>\\'] ?? null);
$i->assertSame('tests/<Ns>Test/', $composer['autoload-dev']['psr-4']['<Ns>Test\\'] ?? null);
}
// Once a real override exists, add a precedence test (the resolver CANNOT be faked by the suite):
// (new \Spryker\Zed\Kernel\ClassResolver\Config\BundleConfigResolver())
// ->resolve(\Pyz\Zed\<Module>\<Module>Config::class) → assertInstanceOf(\<Ns>\Zed\<Module>\<Module>Config::class)
// and assert the override extends the *Pyz* class (not core), plus its payload (e.g. store→warehouse map).
}
code:sniff:stylecodecept build