docs/tutorials/getting-deeper.md
You already know Build from small projects. Here, you will use it in a specific version of Django: first for one bounded command change, then for three related stories defined by one BMad Spec.
:::note[Prerequisites]
Use a macOS or Linux shell with Git, Node.js 20.12+ and npx,
uv, and a coding tool
supported by BMad. Complete Getting Started before
continuing. The exact install and launch commands below are for Claude Code. If
you use another supported tool, you can run Build there instead. VS Code is
optional but useful. Build can open the finished work for you when VS Code's
code command is available.
:::
Clone Django 5.2.4 into a new directory, confirm that you have the expected source code, and create a branch for the exercise:
git clone --depth 1 --branch 5.2.4 https://github.com/django/django.git bmad-django
cd bmad-django
git rev-parse HEAD
git switch -c bmad-getting-deeper
git rev-parse HEAD should print:
c941d0deec0ea08a30670be0fac879f2372f071b
Set up Python 3.12, install your Django checkout so the example app uses it, and create a small Django project next to the repository:
uv python install 3.12
uv venv --python 3.12
uv pip install -e .
mkdir ../bmad-django-app
uv run django-admin startproject tutorial_project ../bmad-django-app
Confirm that JSON output is not yet available:
uv run python ../bmad-django-app/manage.py diffsettings --output=json
The command ends with this error:
manage.py diffsettings: error: argument --output: invalid choice: 'json' (choose from hash, unified)
Install BMad Method from the stable release channel. This exact command sets it up for Claude Code:
npx bmad-method install --directory . --modules bmm --tools claude-code --yes
Tell Git to ignore the BMad files and uv lockfile created for this tutorial:
cat >> .git/info/exclude <<'EOF'
/_bmad/
/_bmad-output/
/.claude/
/uv.lock
EOF
Open your coding tool from the repository root. For Claude Code, run:
claude
/bmad-build Add JSON output support to django-admin diffsettings. Preserve
the existing output formats, add focused tests, and update the command
documentation. Leave the implementation in the working tree for local
inspection.
Build asks any questions it needs before it writes a plan. Answer according to your own preferences for the new JSON output. There is no single required JSON design for this exercise.
Build presents a plan and waits for you to approve it or ask for changes.
Once approved, it builds and reviews the change, handles its findings, and
shows you the result. Keep this exercise about JSON output for diffsettings;
filtering, redaction, and CI behavior belong in the next exercise.
If code is available, Build opens the project and finished spec in VS
Code. The Suggested Review Order links lead you through the change.
Back in your shell, run Django's diffsettings tests:
uv run python tests/runtests.py admin_scripts.tests.DiffSettings --verbosity 1
The tests should pass.
Now run the command again:
uv run python ../bmad-django-app/manage.py diffsettings --output=json
Look through the JSON and compare it with the choices you made with Build.
Congratulations, you've now added something useful to a complex open-source codebase. If you use VS Code, you're probably looking at the finished change there now.
The next change needs three Build runs. /bmad-forge-idea can help you decide
what to build. /bmad-advanced-elicitation can help you improve a draft. You do
not need either here because the requirements are already clear. Send them
straight to BMad Spec:
/bmad-spec Create a spec named diffsettings-audit and break it into
exactly three stories in this order: filters, redaction, then CI status.
Read the current diffsettings implementation, focused tests, and command
documentation before writing the spec. Keep every existing output format
and the JSON design already approved. Add repeatable --include and --exclude
shell-glob filters. Include patterns are OR, and exclusions always win. Add
repeatable --redact shell-glob masks that replace current and default values
with [REDACTED] without changing whether a difference exists. Add
--fail-on-difference, which exits 1 when differences remain after filtering and
0 otherwise. Each story adds focused tests and updates the existing command
documentation. Do not add another Django documentation file or an external
service. Use diffsettings-audit as the spec folder slug.
BMad Spec writes one spec in
_bmad-output/specs/spec-diffsettings-audit/ and the three ordered stories in
its stories.yaml. Read the spec and stories, and answer any questions BMad
Spec asks. Continue when they match the requirements above.
Run Build once for each story, in order. Complete each Build run before moving to the next one. Every run uses the same spec.
/bmad-build Implement story 1, filters, from
_bmad-output/specs/spec-diffsettings-audit/stories.yaml.
After Build finishes, observe the result:
uv run python ../bmad-django-app/manage.py diffsettings \
--include=DATABASES --include=DEBUG --include=SECRET_KEY \
--exclude=DATABASES
printf 'exit: %s\n' "$?"
The output has DEBUG and SECRET_KEY, but no DATABASES, followed by
exit: 0. The include patterns are combined, while the exclusion wins.
/bmad-build Implement story 2, redaction, from
_bmad-output/specs/spec-diffsettings-audit/stories.yaml.
Observe the unified output:
uv run python ../bmad-django-app/manage.py diffsettings \
--output=unified --include=SECRET_KEY --redact='SECRET*'
printf 'exit: %s\n' "$?"
The secret does not appear. Both sides of the difference are masked:
- SECRET_KEY = [REDACTED]
+ SECRET_KEY = [REDACTED]
exit: 0
/bmad-build Implement story 3, CI status, from
_bmad-output/specs/spec-diffsettings-audit/stories.yaml.
Observe a difference that remains after filtering:
uv run python ../bmad-django-app/manage.py diffsettings \
--include=DEBUG --fail-on-difference
printf 'exit: %s\n' "$?"
The DEBUG difference remains visible, and the command finishes with
exit: 1.
Now combine the three stories in one observation:
uv run python ../bmad-django-app/manage.py diffsettings \
--output=json --include=DEBUG --include=SECRET_KEY --exclude=DEBUG \
--redact='SECRET*' --fail-on-difference
printf 'exit: %s\n' "$?"
The JSON contains only SECRET_KEY. Every current or default value exposed by
the JSON shape you chose earlier is [REDACTED]; neither original value
appears. The underlying values still differ, so the final line is exit: 1.
The first exercise gave Build one bounded change directly. This exercise gave three separate Build runs one spec. Filtering, redaction, and CI status still work together at the end. You have extended a mature Django command, and the final result still does what you asked for at the start.
If you want several perspectives on the result, /bmad-party-mode is an
optional final step. You do not need it to finish this tutorial.
Now install BMad in your own repository, then use
the bmad-build skill to make a change you want.