English | 简体中文
Know your code. Mind the gap.
A coding skill that relies on a persistent memory system to compare the technologies used in a codebase with the developer’s current capabilities, record confirmed capability gaps as personal technical debt, and help pay it down.
Important
Clear Code provides the capability-assessment and debt-settlement workflow; it does not store memory. Ongoing use requires a connected persistent memory system to retain current capabilities and supporting evidence across sessions.
-
Copy
skills/clear-code, including its references, into your agent's skill directory:- Project scope:
.agents/skills/clear-code/ - User scope:
~/.agents/skills/clear-code/
Codex and DeepSeek Harness support these locations. DeepSeek Harness needs its filesystem skill provider enabled.
- Project scope:
-
Connect a memory backend to your agent through its existing plugin, MCP tools, CLI, or API. Tell the agent which personal memory to use.
-
Invoke the skill with a real task:
Use clear-code for this task.
Use my connected ReMe memory to track my technical understanding.
Help me choose a background-job approach for this application.
In Codex, you can also invoke $clear-code explicitly. After setup, the agent can select the skill when a task reveals a knowledge gap or new evidence of understanding; automatic selection depends on the host and model.
Code or plan → consequential technologies → capability comparison
→ confirmed gap → personal technical debt
→ targeted learning → new evidence → settlement
Clear Code identifies only the technologies that affect selection, understanding, review, debugging, or maintenance. It compares those requirements with evidence from your current capability record; an unfamiliar technology or a missing memory alone is not debt.
Clear Code supports explicit audits and low-frequency implicit checks.
You state prior experience or unfamiliarity, ask about an unfamiliar technology, or demonstrate new understanding through a decision, review, experiment, or diagnosis. Clear Code checks only that capability.
Completed planning or technology selection turns into substantial implementation, or an unplanned consequential technology appears. Clear Code checks the unresolved frontier once.
You invoke $clear-code or ask to understand or take over an existing module. Clear Code performs the broader module comparison you requested.
Note
Words such as implement, execute, or modify are not triggers by themselves. Routine edits, test execution, ordinary local bug fixes, and continued work inside an already checked scope do not trigger another check.
- Derive and deduplicate relevant technologies before querying memory.
- Use one targeted or batched retrieval, then reuse it within the task.
- Recheck only after a material change in scope, technology, evidence, or remembered revision.
- Never load the full personal profile or query once per file, technology mention, or conversation turn.
Implicit invocation may miss some informal evidence. The implementation checkpoint is the low-frequency fallback.
Technical debt here is personal and portable. It exists only when the current task demands more than the developer can demonstrate and that gap has been confirmed.
When work moves ahead, Clear Code keeps a project-neutral improvement target in the same capability record. Each later task still decides whether that gap is debt in its own context.
| State | Meaning |
|---|---|
| Open | The capability gap currently needs attention. |
| Deferred | The gap remains relevant, but repayment has been postponed. |
| Frozen | No current project or learning goal needs it; preserve the gap without active reminders. |
| Settled | Evidence shows that the developer can perform the target behavior. |
Open and deferred debt do not block the work. AI may move ahead while the gap and settlement target stay explicit. A later relevant task can reactivate frozen debt after checking the new context; it never assumes the old gap still applies.
AI can generate an implementation faster than you can build the judgment needed to review it. Clear Code uses the current task to decide what matters and to gather evidence; the task is not the only way to learn:
- Recall what you understand. Retrieve the relevant capability records, including their scope and evidence.
- Find the next useful gap. Identify the concepts that affect the current decision and learn their prerequisites first.
- Learn in focused steps. Use tailored explanations, concrete examples, guided questions, and small practice exercises. The agent researches facts; you make decisions and explain your reasoning.
- Record demonstrated progress. Update memory when your own explanation, review, experiment, or diagnosis shows a change.
A round contains at most three focused questions. Learning stops when you can handle the current responsibility or explicitly choose to defer it.
For example, choosing a background queue calls for understanding when retries are safe. Later, reviewing its implementation may require spotting how a retried payment could charge someone twice. These demonstrate different depths of the same concept.
| Level | What you can demonstrate |
|---|---|
| Unknown | There is not enough evidence to assess this scope. |
| L0 · Exposure | You are encountering the concept, recognize it, or understand part of it. |
| L1 · Selection | Explain why a solution fits, an alternative, and the relevant tradeoff. |
| L2 · Guidance | Read the important implementation, identify failure conditions, and judge its tests. |
| L3 · Takeover | Independently investigate and fix the relevant problem when taking over is necessary. |
Each assessment applies to a specific capability. Understanding payment retry behavior does not establish mastery of distributed systems. Agreement with an AI answer, generated code, and passing tests alone do not prove your understanding.
A missing memory record means unknown, not unfamiliar. Clear Code asks about prior exposure or lets you demonstrate it before assigning L0. A question, hesitation, isolated terminology mistake, or unclear explanation is not evidence of lower capability.
The task determines the depth needed. Reversible exploration can begin while knowledge is incomplete. A technical choice usually needs L1; reviewing a production change usually needs L2; L3 matters when you need to take over.
Choose technology for its fit to the project. Unfamiliarity identifies something to learn, rather than ruling out a suitable solution.
Clear Code is backend-independent. Any third-party memory system can work if your agent can retrieve, save, and revise or explicitly supersede capability records through its available tools.
No Clear Code-specific API, database schema, or custom service is required. A model endpoint without persistent memory does not meet this requirement.
Recommended starting point for local use. It provides searchable Markdown, keyword search, optional embeddings, related-note retrieval, automatic consolidation, and several agent interfaces.
Consideration: Basic keyword and file operations need no extra LLM calls. Semantic indexing and consolidation can add cost.
On Windows, reme-helper installs and connects ReMe: it manages the service, writes the configuration, and links Codex and DeepSeek Harness to one instance and one workspace.
Convenient if you already use it. Mem0 Platform offers shared memory through Codex and DeepSeek Harness integrations.
Consideration: Platform is managed; OSS is self-hosted and has different integrations. Verify how your tools replace or correct an outdated level.
Useful when deeper association and consolidation matter more than minimum cost. It can link evidence across sessions and build richer memory relationships.
Consideration: Ingestion and reflection can involve additional model calls; deployment and operation are heavier.
These are recommendations based on available interfaces and documented capabilities, not claims that every backend/version combination has been tested with this skill. Other backends are equally usable when their tools provide the same practical behavior.
The skill saves concise current capability records and supporting evidence, retrieves only what the task needs, and avoids writing unchanged assessments.
Backend consolidation can organize and connect those records; generated summaries do not count as new evidence of mastery. Recall quality, write latency, and total token cost depend on the backend and configuration.
Codex Desktop, VS Code Codex, and DeepSeek Harness Web can load the same English skill files. Each host also needs access to the chosen memory tools. Install the skill and connect the same personal memory in each host to carry your understanding between them.
Shared live use requires access to the same memory service. To move to another computer, use your provider's export/restore or workspace backup, preserving the readable records and evidence. A copied workspace alone does not synchronize two independently edited instances.
Project requirements and decisions remain in project documents and code. Clear Code records your technical understanding. Other memories may coexist in the same service; they are not automatically evidence of your ability.
If memory is unavailable, the agent can still help with the current task and show an unsaved update. Cross-session continuity resumes when the memory connection works.
MIT.