The Permanent Rules File: P1–P13

Claude Rules Workflow

Chapter 3 · The Permanent Rules File: P1–P13

permanent_rules.md is the single largest, most-load-bearing file in the whole @rules/ include list from Chapter 1 — it's what actually governs how every numbered course on this site gets written, saved, and tracked. Rather than read it rule by rule in the abstract, this chapter tours it the way it's actually used day to day, with a few rules singled out for a closer look because you're looking at them in action right now.

The Full Rule Set at a Glance

Rule	Governs	One-line summary
P1	Banner headers	Every generated file opens with a Course/Chapter/File/Topic/Date comment
P2	Storage location	content/[subject]/[course]/ — a fixed, predictable folder shape
P3	Progress reports	The bare word "progress" triggers a saved, dated status summary
P4	Completion PDFs	A course's final chapter automatically triggers a combined book-style PDF
P5	Prompt convention	topic<course>-<chapter> — this exact chapter was requested as "rules1-3"
P6	PDF book format	Dark cover, light interior, table of contents, page numbers
P7	Tracking-file sync	completed_courses.md and course_bucket_list.md updated the SAME turn a course finishes (Chapter 7)
P8	Python lesson format	Moved to programming_lesson_rules.md — the base case Chapter 5 covers alongside PL1–PL3
P9	"Flesh out" convention	Writes a full course outline into the bucket list — literally how this course was born (see below)
P10	Q&A capture	"add this to q&a" saves a real exchange into faqs/qa_with_claude.md
P11	Cross-chapter references	Reader-facing text uses full course names, never a shorthand prompt prefix
P12	Code block formatting	Real syntax highlighting, ASCII trees inside <pre>, a shared copy-to-clipboard button
P13	Agent-question capture	Questions about Claude Code agents auto-save to faqs/agent_questions.md, no trigger phrase needed

Spotlight: P1 — The Banner You're Looking At Right Now

Every generated course file opens with a fixed-shape HTML comment — this very chapter's own file starts with exactly this structure:

<!-- ============================================================
     Course: Claude Rules Workflow
     Chapter: The Permanent Rules File: P1–P13
     File: claude_rules_workflow_1_3.html
     Topic: ...
     Date Created: 2026-08-20   Date Updated: 2026-08-20
     ============================================================ -->

Once a fragment has no genuine <h1> of its own, the site's own build pipeline uses this banner's Chapter: field as the page's real title and breadcrumb — which is exactly why every chapter in this course opens with a .course-name/.chapter-sub pair instead of repeating the chapter name as a second, near-duplicate heading.

Spotlight: P5 — The Prompt That Produced This Chapter

The short prompt rules1-3 follows P5's own shape exactly: a topic prefix (rules1), no colon, no spaces, a hyphen, then a chapter number. Because Chapter 9 of the fleshed-out outline (see the next spotlight) already existed, this prompt generated the chapter directly — no outline step needed, since P5 only forces an outline-first pause on a course's very first, `-1` chapter with no existing outline at all.

Spotlight: P9 — How This Very Course Came to Exist

This is the most self-referential rule in the whole file, and worth calling out directly: the prompt flesh out rules1 is what produced the 10-chapter outline this course is currently working through. P9 doesn't generate any chapter content — its entire deliverable is the outline itself, written straight into course_bucket_list.md for review. That's exactly what happened here: a short bucket-list one-liner about a stale, orphaned PDF became a real, numbered chapter list, and only afterward did chapter-by-chapter generation begin.

A course about the rules, generated by following the rules

Every mechanism this course documents — P1's banner, P5's prompt shorthand, P9's outline-first flow, and (once this course finishes) P4's automatic PDF and P7's bookkeeping sync — is being used, unmodified, to actually produce this course. There's no special-cased "meta mode." That's a genuine, checkable demonstration that the system is consistent, not just a description of one.

Spotlight: P7 — Why This Course Doesn't Have a PDF Yet

P4 triggers a combined PDF specifically when a course's final chapter is generated — not before. Since this course is only three chapters into ten, no combined PDF exists yet, and completed_courses.md correctly doesn't list it as finished. Chapter 7 covers the full discipline behind keeping that file, plus course_bucket_list.md, in sync — including the rule that both get updated in the very same turn a course's last chapter lands, never deferred to "later."

P11 in practice — this paragraph itself follows it

Notice this chapter never writes a bare prompt-shorthand reference like "see php2-4" in its own reader-facing prose — it always spells out the real name, e.g. "PHP Intermediate 4." A prompt prefix like rules1 is meaningful shorthand for generating chapters, but meaningless to an actual reader who's never seen this project's own internal conventions.

Spotlight: P12 — The Copy Button on Every Code Block Above

Every code block in this chapter is wrapped in a .code-block-wrap with a small "Copy" button in the corner — but notice there's no <script> tag defining that button's behavior anywhere in this file. Per P12, the actual copyCodeBlock function lives once, globally, in the site's shared layout — not duplicated into every single chapter — specifically because a chapter fragment gets injected into the page via an innerHTML-equivalent mechanism, and an embedded <script> tag inside injected content never executes in that situation.

Coding Challenges

Challenge 1

Explain, using P1 and P5, why the banner comment at the top of this chapter's own file and the prompt "rules1-3" contain overlapping but not identical information (both reference the course and chapter, but only one contains a date).

📄 View solution

Challenge 2

A user sends the prompt "flesh out imagemagick1" for a topic that's never been mentioned before. Based on P9's own description, what should Claude actually produce in response — and what should it NOT produce yet?

📄 View solution

Challenge 3

This chapter's own code blocks all have working Copy buttons on the live site, with zero <script> tag inside this chapter's own HTML file. Explain why, referencing P12's own reasoning about injected content.

📄 View solution

Chapter 3 Quick Reference

P1 — every generated file opens with a Course/Chapter/File/Topic/Date banner comment
P2 — fixed content/[subject]/[course]/ storage shape
P3 / P4 / P6 — progress reports, completion PDFs, and the dark-cover/light-interior book format behind them
P5 — the topic<course>-<chapter> prompt shorthand, e.g. "rules1-3" for this very chapter
P7 — completed_courses.md and course_bucket_list.md updated the same turn a course finishes, never deferred (Chapter 7)
P8 — moved out to programming_lesson_rules.md; covered in Chapter 5 alongside PL1–PL3
P9 — the "flesh out" convention that produced this exact course's own 10-chapter outline
P10 / P13 — two automatic capture conventions (Q&A archive, Claude-agent-question log)
P11 — reader-facing text always uses full course names, never a bare prompt prefix
P12 — real syntax highlighting and a shared, globally-defined copy-to-clipboard button, not a per-file <script>
Next chapter: the natural-language lesson rules, L1 through L7