docs: spec-system v0.1 design (layered spec architecture)#100
Merged
Conversation
Captures the architecture chosen after a brainstorm + research pass + eng review for extending CHARTER into a layered spec system that survives multi-day autonomous agent execution. Selected tier: M (right-sized) — zero new skills, single new file family (spec/capabilities.md), two new scripts (extract-signals + append-learnings). Strangler-fig path to L tier preserved but not paved. Three research findings load-bear the design: the 3-mode failure taxonomy (misspecification / goal misgeneralization / adversarial Goodhart), the control-theory framing (CHARTER as setpoint, ## Learnings as minimum viable sensor), and immutability-after-acceptance as the universal stability discipline across spec frameworks. Implementation plan is 3 PRs: template + grill-mode SKILL extension, brownfield bootstrap (extract-signals.js), live-update wiring (cross-repo with dev-relay). Dogfood targets: dev-backlog itself, then dev-relay. CHARTER alignment: advances O3/O4 (still active — needs independent-project proof before status advance); O5 stays deferred but Learnings is its manual precursor. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
개요새로운 문서 변경사항레이어드 스펙 시스템 설계 문서
예상 검토 난이도🎯 3 (Moderate) | ⏱️ ~20분 시
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (2)
docs/spec-system-design.md (2)
110-110: 💤 Low value코드 블록에 언어 지정자 추가를 고려하세요.
구현 계획 다이어그램에도 언어 지정자(예:
text)를 추가하면 린터 경고를 해결할 수 있습니다.♻️ 제안된 수정
-``` +```text PR-1: template + SKILL.md extension (no executable code)🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/spec-system-design.md` at line 110, Update the fenced code block that contains "PR-1: template + SKILL.md extension (no executable code)" to include a language specifier (e.g., change the opening fence to ```text) so the linter warning is resolved; locate the code fence in docs/spec-system-design.md and replace the opening ``` with ```text for that block.
40-40: 💤 Low value코드 블록에 언어 지정자 추가를 고려하세요.
마크다운 린터가 펜스드 코드 블록에 언어 지정을 권장합니다. 디렉터리 구조 다이어그램이므로
text또는 빈 문자열을 사용할 수 있습니다.♻️ 제안된 수정
-``` +```text repo/ ├─ CHARTER.md ← Tier 1 (frozen-ish, 5-min read, north star)🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/spec-system-design.md` at line 40, The fenced code block containing the directory diagram in docs/spec-system-design.md currently has no language specifier; update the opening fence from ``` to ```text (or another appropriate language like an empty string) so the Markdown linter recognizes it as plain text and preserves formatting—locate the fenced block that starts with the "repo/" tree and change the fence to include the language identifier.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@docs/spec-system-design.md`:
- Line 110: Update the fenced code block that contains "PR-1: template +
SKILL.md extension (no executable code)" to include a language specifier (e.g.,
change the opening fence to ```text) so the linter warning is resolved; locate
the code fence in docs/spec-system-design.md and replace the opening ``` with
```text for that block.
- Line 40: The fenced code block containing the directory diagram in
docs/spec-system-design.md currently has no language specifier; update the
opening fence from ``` to ```text (or another appropriate language like an empty
string) so the Markdown linter recognizes it as plain text and preserves
formatting—locate the fenced block that starts with the "repo/" tree and change
the fence to include the language identifier.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 8bcd9af7-f609-4e1e-8d6b-1e9bb509c20a
📒 Files selected for processing (1)
docs/spec-system-design.md
This was referenced May 23, 2026
This was referenced May 23, 2026
This was referenced May 29, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Design doc capturing the chosen architecture for extending CHARTER into a layered spec system that survives multi-day autonomous agent execution.
Summary
What lands now
What lands in follow-up PRs (3-PR plan)
CHARTER alignment
Advances O3 + O4 (status stays `active` — needs independent-project proof per Tier 2). O5 stays deferred; `## Learnings` is its manual precursor.
Test plan
🤖 Generated with Claude Code
Summary by CodeRabbit
릴리스 노트