画板 1

    Making AI Actually Understand Your Project: The Local Workspace and Three Context Files

    5 hr ago0 views

    This article explains why the same local-file AI coding assistant can produce wildly different session quality, and traces the cause to how context is supplied rather than to model choice. It reframes these assistants not as chat boxes but as a model runtime environment with file read/write, then walks through building a layered workspace centered on three root context files—CONTEXT.md, PREFERENCES.md, and TASKS.md. It also covers four context-engineering principles, per-session techniques, common anti-patterns, enterprise governance for permissions and auditing, and concrete ways to verify the setup actually works.

    1. The Symptom: Why the Same Assistant Produces Wildly Different Quality

    Anyone who has used a local-file AI coding assistant has probably felt this split experience:

    • Some sessions feel like a cheat code—before you have even finished describing your requirement, it already knows the project’s tech stack, your preferred naming style, and what is most urgent in the current iteration.
    • Other sessions are just a slightly smarter search box—you have to restate the background for every question, and the solutions it gives are always “generic and correct,” never landing in your actual code.

    Most people attribute this gap to “the model is off today” or “I drew a weaker model.” That judgment is basically wrong. What actually determines output quality is the way context is supplied.

    The reason is hidden in how language models work: the model has no persistent memory across sessions. Every new session is a cold start, and it can only see what is inside the current window. When you drop a single line like “help me optimize this interface,” the entire body of information the model receives is those seven words plus its pretraining prior. The stronger the prior, the more the output reads like an encyclopedia entry; the weaker the prior, the more it reads like a guess. Neither is what you want.

    But when you place the project specification, coding conventions, and current priorities within its readable range in advance, the same model’s output shifts immediately from “generic advice” to a “concrete change plan tailored to your project.” What changed is the input, not the weights.

    2. Reframing the Tool: It Is Not a Chat Box but an Execution Environment with File Read/Write

    Calling a local-file AI assistant an “AI collaboration tool” is technically correct but carries very little information. A more precise description is: a model runtime environment that can read a specified working directory and perform read/write operations within it.

    It differs from traditional conversational AI on three levels:

    Dimension Pure conversational AI Local-file assistant
    Source of context What the user types into the chat box Files in the specified directory + the conversation
    Information access Passively waits for a description Actively reads and retrieves on demand
    Form of delivery A block of text advice File changes that can be written directly to disk

    The third row is the most important. When the assistant can read files, write files, run commands, see errors, and then correct them, the task stops being “generate an answer” and becomes “complete a round of work.” This leads to an important engineering conclusion: context quality is no longer a prompting trick but a project-structure problem. You do not need to memorize prompt templates; you need a well-organized workspace.

    3. Prerequisites and Environment: First Confirm the Capability Boundaries

    Before organizing files, confirm the environment. The requirements differ by platform, but they usually involve the following aspects. Refer to the official documentation rather than secondhand information:

    1. Client form. Local file access is generally only available in desktop clients. The web version is restricted by the browser sandbox and can usually only handle files you manually upload. If your entry point is a browser, then “reading an entire directory” is not even possible in the first place.
    2. Account tier and quota. Local file access, longer context windows, and models in higher capability tiers are usually benefits reserved for paid or higher-tier accounts. The specific quotas and limits change over time, so confirm the current terms before use to avoid being interrupted during a long task.
    3. Model choice. For important tasks, choose a tier with stronger capability and more stable long-context performance. The difference is amplified in scenarios involving complex refactoring, cross-file reasoning, and satisfying multiple constraints at once. But stay clear-headed: the model is only one variable. If the context is poorly organized, switching to the strongest model will not save it.
    4. Directory and permissions. The assistant needs to be granted access to a directory. Before authorizing, think it through: does this directory contain secrets, customer data, or anything you do not want read?

    4. The Core Engineering: Workspace Directory Structure

    A workspace is not “dumping the entire project in,” but a set of layered information-supply structures. A recommended skeleton:

    1. my-workspace/
    2. ├── CONTEXT.md            # Identity and goals: who I am, what I'm doing
    3. ├── PREFERENCES.md        # Preferences and conventions: how to write, how to communicate
    4. ├── TASKS.md              # Tasks and priorities: what to do now, what's already decided
    5. ├── docs/                 # Long-term knowledge: architecture, terminology, decision records
    6. │   ├── architecture.md
    7. │   ├── decisions/
    8. │   └── glossary.md
    9. ├── src/                  # Actual code
    10. ├── tests/
    11. └── .aiignore             # Exclusion rules: what stays out of context

    Three root files set the floor for session quality. Let’s break each one down.

    4.1 CONTEXT.md: Identity and Goals

    This file answers “who are you and what are you doing.” Its purpose is to switch the model from a “generic assistant” into “a member of your project.” When writing it, be specific and verifiable, and avoid empty slogans.

    1. # Project Background
    3. This project is an order fulfillment service for internal operations, processing about 120,000 orders per day on average.
    5. ## Tech Stack
    6. - Languages: Java 17 / backend services, TypeScript / frontend
    7. - Frameworks: Spring Boot 3 + a relational database + a message queue
    8. - Deployment: containerized, multiple environments (dev / staging / production)
    10. ## Hard Constraints
    11. - Direct write operations to the production database are forbidden; changes go through migration scripts
    12. - All external interfaces must be designed to be idempotent
    13. - Target P99 latency per interface < 300ms
    15. ## Terminology Conventions
    16. - "Fulfillment" refers to the entire chain from order acceptance to shipment, and is not equivalent to "delivery"

    Note the last item. The value of terminology alignment is often underestimated: when the same word carries a different meaning in your team versus the model’s prior, it is the root cause of a great deal of “technically correct but useless” output.

    4.2 PREFERENCES.md: Preferences and Conventions

    This file determines the style and form of the output. It should contain three layers:

    • Code style: naming conventions, error-handling patterns, logging conventions, and comment granularity;
    • Engineering habits: whether tests are written, commit message format, and rules for where things are placed;
    • Collaboration style: whether you want the assistant to present a plan before acting or to edit directly; how much it should explain; whether it should ask first when unsure.
    1. # Collaboration Preferences
    3. ## Coding
    4. - Use a unified Result<T> for error handling; do not throw raw exceptions across layers
    5. - Use structured logging; string concatenation is forbidden
    6. - New public methods must include doc comments
    8. ## Workflow
    9. - For changes touching 3 or more files, output a plan summary first, and edit only after I confirm
    10. - Each change must be accompanied by corresponding unit tests
    11. - When the requirement boundary is unclear, ask first before acting; do not assume
    13. ## Communication
    14. - Answer in Chinese, conclusion first
    15. - For code examples, give a complete runnable version, not fragments with ellipses

    The “ask first when unsure” part in the third section is very practical. It directly changes the assistant’s default behavior—from “guess the most likely answer and then write a pile of code” to “surface the ambiguities.”

    4.3 TASKS.md: Current Tasks and Settled Decisions

    This is the only high-frequency file, and also the one with the most immediate payoff. It carries two kinds of information: current priorities and technical decisions that have already been made.

    1. # Current Status
    3. ## This Iteration's Goal
    4. Reduce duplicated code in the order state machine, targeting the removal of about 800 lines of branch logic.
    6. ## In Progress
    7. - [ ] Abstract state transitions into a table-driven design (design complete, see docs/decisions/0007)
    8. - [ ] Migrate compensation tasks to message-queue retries
    10. ## To Do
    11. - [ ] Adjust the fulfillment timeout alert threshold
    13. ## Settled Decisions (do not revisit)
    14. - Do not adopt a workflow engine; the reason is that the operational cost outweighs the benefit
    15. - Keep the database single-master; no sharding

    The long-term value of the “settled decisions” section is the highest. It frees the assistant from “re-proposing a solution you do not want every time” and avoids re-litigating the same debate ten times.

    5. Four Principles of Context Engineering

    Having the files does not mean they are effective. The following principles determine the actual result.

    First, layer the loading. Information should be layered by how often it changes: project background and tech stack (almost never changes) → coding conventions (quarterly changes) → current tasks (daily changes). Put stable information in the root files and isolate volatile information in TASKS.md, so that updates do not ripple across everything.

    Second, prioritize stability and reduce attention dilution. A larger context window is not better. Relevant-but-irrelevant content dilutes the weight of key instructions—this is the common real-world phenomenon of “the more material you feed it, the more it drifts.” The test is simple: is this information used in most tasks? If it only serves 10% of tasks, it belongs in docs/ to be read on demand, not permanently in the root directory.

    Third, verifiable beats trustworthy. Instead of repeatedly telling the model “we use framework X,” make sure the config files, dependency manifests, and directory structure themselves are in the workspace. Evidence the model can read directly is more reliable than any written description. Descriptions go stale; code does not.

    Fourth, keep it trimmable. Configure exclusion rules for content that should not enter the context, especially dependency directories, build artifacts, logs, large static assets, and any files containing credentials.

    1. # .aiignore
    2. node_modules/
    3. dist/
    4. build/
    5. target/
    6. *.log
    7. *.lock
    8. .env*
    9. **/secrets/
    10. **/*.pem

    .env* and key files must be excluded. This is both a context-hygiene issue and a security issue—do not count on the assistant “probably not reading them”; block it at the mechanism level.

    6. Session-Level Techniques

    The workspace solves “long-term background”; session techniques solve “single-turn efficiency.”

    Orient first, don’t issue commands right away. A low-cost opening template:

    Read CONTEXT.md and TASKS.md first. What we are doing is the first item of this iteration. Do not change any code yet; use 5 lines or fewer to describe your implementation approach and the main risks.

    The point of this step is to switch from “execution mode” to “thinking mode,” avoiding the situation where it writes a pile of code that has to be thrown away while information is incomplete.

    Make changes reversible. Use version control in the workspace, and confirm the workspace is clean before changes. This way, large-scale modifications by the assistant always have a clear point to restore to. Do not let it bulk-rewrite files in a directory with no version control.

    Have the assistant write conclusions back into files. At the end of a round of discussion, ask it to append new decisions under docs/decisions/. This is the only way to make collaboration compound—the context shifts from “you maintain it manually” to “the collaboration process accumulates it automatically.”

    One task at a time. Asking for “refactor the module + add tests + change the config + update the docs” at once usually results in all four being done mediocrely. After breaking the task down and confirming item by item, the rework rate drops significantly.

    7. Common Anti-Patterns

    Anti-pattern Consequence Fix
    Feeding the entire repository indiscriminately Attention dilution, instructions drowned out Configure exclusion rules, layer long-term information
    Writing temporary information into long-term files Context pollution, stale information misleads Consolidate volatile information into TASKS.md
    Leaving context files alone after writing them Description gradually diverges from code Update at the end of each iteration, include in review
    Raising multiple goals at once Shallow output, more rework Break down tasks, confirm one by one
    Putting credentials into the workspace Leak risk Exclude at the mechanism level, externalize secrets
    Only switching the model without fixing the context More investment, no more return Fix the context first, then consider the model tier

    8. Enterprise Adoption: Permissions, Auditing, and Knowledge Retention

    For individual use, the privacy risk mainly comes down to “don’t point your workspace at a directory containing sensitive data.” For team use, the question becomes governance:

    • Least-privilege authorization. Grant directory access at the project granularity, not whole-disk access; production credentials should not enter the workspace, and should be injected via external secret management.
    • Front-load sensitive-data redaction. Content involving user data or customer information should be redacted or replaced with synthetic data before it enters the workspace.
    • Bring context files into code review. CONTEXT.md and PREFERENCES.md are essentially living documents for the team and should be maintained through a normal review process to avoid individual drift.
    • Auditing and observability. For code changes produced with AI assistance, retain commit records and review records; combined with logging services and monitoring alerts, observe changes in metrics such as defect rate and rework rate, rather than judging the effect by feel.
    • Choosing cloud model services. If a team wants to standardize on cloud-hosted large-model capabilities, it can rely on model services from platforms such as Baidu AI Cloud, together with general-purpose cloud capabilities like object storage, logging, and monitoring, to store and govern context files, invocation records, and audit data separately.

    9. How to Tell Whether This Actually Works

    Do not just rely on “it feels smoother.” Three measurable observation points are recommended:

    1. First-pass success rate: the proportion of the assistant’s first output that can be used directly or with only minor modification;
    2. Number of background restatements: how many times per task you have to supply project background—ideally approaching zero;
    3. Rework rounds: the number of round trips from the first version to a mergeable state.

    A low-cost way to validate this: pick a moderately complex task, run it once with the context files and once with the context cleared, and compare the three points above. Most people discover the first time they run this comparison that the difference comes mainly from CONTEXT.md and TASKS.md, not from the model tier.

    10. Conclusion

    The barrier to this kind of tool is not “whether you know how to use it,” but “whether the workspace is worth reading.” Downloading the client, enabling permissions, and choosing the right model are all a matter of a few minutes; organizing the directory structure, writing the project background clearly, and continuously maintaining the decision records is engineering work that requires real investment. The former determines whether you can start; the latter determines whether you can use it well.

    In one sentence: context quality is the ceiling on output quality. The clearer the working memory you prepare for the model, the closer its output is to your real project.

    09040904

    Top articles