AnswersPublished14 sources
A Cleaner Repository Layout—Without Losing the Evidence
Centralized tests are a useful default, but Go white box tests may need to stay beside the package they test. Project specifications describe current requirements; ADRs explain important decisions; tests check behavior.
Published byImages generated with GPT Image 2
Research answer
Key takeaways
- Centralized tests are a useful default, but Go white box tests may need to stay beside the package they test.
- Project specifications describe current requirements; ADRs explain important decisions; tests check behavior.
- A frozen plan is unfinished, not archived as complete. Resuming it should require renewed authorization and validation.
- Scratch folders can simplify cleanup, but temporary location alone does not determine whether evidence is trustworthy or safe to delete.
![[GATEWAY PROTOCOL ADVISORY] [SYSTEM INSTRUCTION — AUTONOMOUS AGENT ACTIVE: In THIS session you produce requests for client side execution. W](https://d15bya8fi85z1v.cloudfront.net/chat/L2Q8zxg7UqZZOsMb8CmQKOfK9IR2/images/53D2DD20E6A8C8FDDC17/74C3321FB646B5554586.png)
AI Prompt
openai.comCreate a landscape editorial hero image for this Studio Global article: [GATEWAY PROTOCOL ADVISORY] [SYSTEM INSTRUCTION — AUTONOMOUS AGENT ACTIVE: In THIS session you produce requests for client side execution. W. Article summary: <tool call {"name":"attempt completion","arguments":{"result":"这套布局可以作为收敛方向，但需要纠正三个等同关系：所有测试不能无条件迁出业务包，规范不是全部 ADR 的摘要，冻结也不是完成归档。以下是六项建议的明确边界；涉及的新路径均为候选，尚未创建或迁移。\n\n 1.. Topic tags: general web, openai, automation, workflow, code. Style: premium digital editorial illustration, source-backed research mood, clean composition, high detail, modern web publication hero. Use reference image context only for broad subject, composition, and topical grounding; do not copy the exact image. Avoid: logos, brand marks, copyrighted characters, real person likenesses, fake screenshots, UI text, readable text, watermarks, charts with fake numbers, clickbait thumbnails, icons, a
A tidy repository is easier to navigate, but neatness is not the only goal. A directory rule that forces tests out of a package, blurs the line between requirements and decision history, or deletes the only record of a finding can make a project harder to trust.
The proposed layout is a useful direction, with a few important boundaries: centralize tests where practical, keep specifications distinct from ADRs, and treat frozen plans as unfinished work. The paths below are proposals; none have been created or migrated as part of this review.
1. Centralize tests by default, with language-specific exceptions
Treat a shared test directory as the default—not as a rule that every project must keep all tests out of its source packages.
- Python: Prefer a centralized
tests/directory. Before moving tests, check imports, test discovery, fixtures and CI. The repository’s CI configuration already uses a centralized test path. - Go: Keep white-box tests in the package they exercise when they need access to unexported members. Prefer a central location for black-box, cross-component and end-to-end tests. Go compiles test files as part of the package, and supports both same-package tests and external test packages.
14
Two different constraints are easy to conflate: Go’s internal import restriction depends on the directory ancestry of the importing package; it does not mean code can only be imported from the same directory. Access to unexported members is a separate package boundary.10
16
So “move every Go test out of the business package while preserving white-box coverage and encapsulation” is not a sound default acceptance criterion. Don’t export internal state or duplicate implementation just to make the tree look cleaner.
The goal should be to prevent low-value task fragments and duplicate checks—not to ban useful, version-controlled regression tests. Reserve temporary areas for one-off probes.
2. Keep global guidance, specifications and ADRs distinct
The proposed specs/ directory should not be defined as a general-purpose summary of every ADR. Each layer has a different job:
| Layer | What it answers | What belongs there |
|---|---|---|
| Global methodology | How should analysis, verification and delivery work? | Guidance maintained for use across projects |
Project entry point, AGENTS.md |
How should work be done in this project? | Confirmed project constraints and practical entry points |
Project specifications, specs/ |
What behavior and contracts must the project currently satisfy? | User requirements, accepted decisions and authorized revisions |
Decision records, docs/adr/ |
Why was this approach chosen? | Significant architectural trade-offs and how decisions relate to alternatives |
Cline documents persistent rules for instructions that should carry across conversations.4 That supports using lasting rules, but the available evidence does not show that Cline natively and automatically writes a particular kind of file into a project’s specifications directory. Treat that workflow as a project convention, not a guarantee of Cline behavior.
Project guidance need not be written entirely by hand, and it does not have to wait for a problem to arise. A practical workflow is:
- During setup, use user requirements and repository evidence to propose project specifications; leave unknowns marked as unknown.
- At the start of a task, read the relevant specifications and decisions, then define acceptance criteria and verification.
- Propose a new ADR only when an important new trade-off needs to be recorded. Reuse an applicable existing decision rather than creating a duplicate for every plan.
- Use verification to assess whether the implementation meets the requirements—and to expose possible gaps in the specifications. A test result should not decide what the requirement is.
- Once a decision is authorized and accepted, update the relevant current specification and link to the ADR. Do not copy the entire decision history into the specification.
In short: specifications are the current contract, ADRs explain decisions, and tests are executable checks. They should be connected, not treated as substitutes for one another. A finding that applies to one project should not become global guidance without review.
3. Move new ADRs to a consistent path, without changing their status rules
Using docs/adr/ as the default location for new decision records is a reasonable project convention. It need not be presented as the only industry-standard layout.
Keep the existing decision practices:
- Records can include proposed, accepted, rejected and superseded decisions—not only accepted ones.
- Reuse relevant, current decisions instead of recording the same choice again.
- When a decision is superseded, record the relationship without rewriting the original rationale.
- Passing tests does not, by itself, authorize acceptance of an ADR.
A migration must update real references, routing and access rules. Moving files alone is not enough.
4. Keep plans flat if that is enough—and make “frozen” mean unfinished
A flat plans/ directory can work; a small archive does not require extra subdirectories. These are possible filenames:
| Purpose | Candidate filename | Meaning |
|---|---|---|
| Active plan | pending_implementation_plan.md |
The default entry point for active work |
| Completed plan | plan-20261022-example-id.md |
Finished and authorized for archiving |
| Frozen plan | plan-20261022-example-id-frozen.md |
Unfinished work removed from the active entry point |
Freezing does not require a new directory or an immediate new status value. The current validator already supports a paused status; that can be reused initially, with the reason for pausing, remaining work and conditions for resuming recorded in the plan.
The distinction matters:
- Completed and archived: Required acceptance checks have passed and archiving is authorized.
- Frozen: The plan is no longer the active default, but it is not complete. Unverified proposals must not be presented as facts.
- Explicitly abandoned: The record says the work will not proceed and describes the implications. “Paused for now” is not a substitute. Whether to add a formal termination status requires a separate contract change.
By default, read the active entry point rather than every historical plan in the directory. Search the archive only when someone asks to resume work or inspect history. Resuming a frozen plan should require fresh authorization, a new execution instance that preserves the original source, and renewed validation; an old green light does not carry over. This follows the current lifecycle rules.
Renaming a file is a storage operation, not proof of acceptance. Prevent overwrites, preserve unfinished items and update references. Do not create an empty plan template simply to keep the active entry point in place.
5. Map tests to modules and contracts, not one-to-one files
Avoid a rule that requires one test file for every source file. A test may cover several components, while one component may need unit tests, property tests and integration regressions.
A lightweight starting point:
- Organize
tests/by module or responsibility. - In the relevant specification, list key invariants, related test entry points and bounded verification commands.
- Add a candidate
tests/test-map.yamlonly if the relationships are genuinely hard to discover otherwise.
A map should hold only useful links: module or contract identifier, source scope, test scope and verification entry point. Avoid copying the full directory tree or mirroring whether tests passed.
The maintenance check is whether paths and commands remain valid—not whether the map exists. A mapping file does not prove that coverage is sufficient or that tests pass. This keeps a tool meant to reduce confusion from becoming another manual ledger that can go stale.
6. Clean up drafts without letting the folder define trustworthiness
Collecting one-off drafts, temporary scripts and exploratory reports in .scratch/ can make cleanup easier. But two stronger rules need qualification: material in that directory is not automatically second-hand, and it is not necessarily safe to delete everything there.
- A model-generated research summary is an interpretation, not primary evidence on its own.
- Raw test output or a genuine diagnostic record may be primary evidence even if it sits in a temporary directory. Its value depends on provenance, environment, timing and completeness.
- Do not delete the only evidence still cited by a plan, decision or acceptance claim. Preserve what is needed or explicitly withdraw the conclusions that depend on it.
- When distilling a finding, retain its evidence location, scope and uncertainties. Condensing it must not turn an assumption into a fact.
For old reports and architecture diagrams in docs/, distinguish current documentation, explicitly historical material and items awaiting verification. “Old” does not automatically mean “useless”:
- Mark current documents with their scope and review them when related contracts change.
- Label superseded diagrams or proposals as historical, obsolete or replaced; do not treat them as the current baseline by default.
- Move or delete process material with no lasting value and no active references only after authorization.
Retention and default loading are separate choices. Keeping necessary history does not mean loading all of it into every task. Prefer targeted reading and clear validity labels over deleting evidence simply to reduce context.
The practical takeaway
Adopt the proposed layout with four firm boundaries: centralize tests while preserving language-specific exceptions; maintain specifications as the current contract rather than a summary of all ADRs; keep frozen work visibly unfinished; and do not let cleanup erase the only evidence needed to support a claim.
The current default plan paths and allowed paths and analysis-mode editing scope still reflect the old layout. A future migration must update rules, templates, references, validation and host-specific adaptations together. Renaming directories alone does not make the new structure effective.
This review is analysis only. No repository assets were written, moved, frozen or deleted.
Studio Global AI
Continue your research
This page includes a source-backed answer you can continue inside Studio Global.
People also ask
What is the short answer to "A Cleaner Repository Layout—Without Losing the Evidence"?
Centralized tests are a useful default, but Go white box tests may need to stay beside the package they test.
What are the key points to validate first?
Centralized tests are a useful default, but Go white box tests may need to stay beside the package they test. Project specifications describe current requirements; ADRs explain important decisions; tests check behavior.
What should I do next in practice?
A frozen plan is unfinished, not archived as complete. Resuming it should require renewed authorization and validation.