diff --git a/dist/claude-code/structured-coding/references/agent-workflow.md b/dist/claude-code/structured-coding/references/agent-workflow.md index 6e84145..e2b992d 100644 --- a/dist/claude-code/structured-coding/references/agent-workflow.md +++ b/dist/claude-code/structured-coding/references/agent-workflow.md @@ -22,7 +22,16 @@ Keep these documents together under `.structured-coding/plans/`, one directory p .structured-coding/plans/infra-exp-p0/handoff.md ``` -That is the default, not a requirement. A project that already keeps planning documents somewhere else should keep them there; what matters is that one location is the authority and that a later session can find it. Commit them if later sessions or teammates need to read them, which is usually the point of writing them down. +That is the default, not a requirement. A project that already keeps planning documents somewhere else should keep them there; what matters is that one location is the authority and that a later session can find it. + +Planning documents are development artifacts and default to staying out of version control, alongside the personal standards overlay: + +```text +.structured-coding/plans/ +.structured-coding/standards.local.md +``` + +The shared standards file is the deliberate exception: `.structured-coding/standards.md` is project configuration, and whether Git tracks it is exactly what makes it the team's standard rather than one developer's, so it belongs in version control. Keeping plans local costs a teammate the ability to read them from a fresh clone, while a later session on the same machine still finds them. Commit them when that tradeoff runs the other way for your project. Do not create additional tracking documents that compete with the primary PR ledger. The contract can be a section of the PR design or a separate linked document. The handoff is a continuation aid, not another design authority. diff --git a/dist/claude-code/structured-coding/references/agent-workflow.zh-CN.md b/dist/claude-code/structured-coding/references/agent-workflow.zh-CN.md index 24d142d..4753437 100644 --- a/dist/claude-code/structured-coding/references/agent-workflow.zh-CN.md +++ b/dist/claude-code/structured-coding/references/agent-workflow.zh-CN.md @@ -22,7 +22,16 @@ .structured-coding/plans/infra-exp-p0/handoff.md ``` -这是默认做法，不是硬性要求。项目如果已经把规划文档放在别处，就继续放在那儿；真正要紧的是只有一个位置是权威，而且后续 session 找得到它。如果希望后续 session 或队友能读到，就把它们提交进版本库——写下来通常就是为了这个。 +这是默认做法，不是硬性要求。项目如果已经把规划文档放在别处，就继续放在那儿；真正要紧的是只有一个位置是权威，而且后续 session 找得到它。 + +规划文档属于开发产物，默认**不进版本库**，和个人的 standards 覆盖文件一起： + +```text +.structured-coding/plans/ +.structured-coding/standards.local.md +``` + +共享的 standards 文件是刻意的例外：`.structured-coding/standards.md` 是项目配置，而"git 有没有 track 它"恰恰就是它成为团队标准而不是某个人标准的判据，所以它应该进版本库。把 plans 留在本地的代价是队友从全新 clone 里读不到它们，而同一台机器上的后续 session 仍然找得到。如果对你的项目来说这个取舍反过来更合适，就提交它们。 不要创建与 primary PR ledger 争夺权威的额外跟踪文档。contract 可以是 PR design 的一节，也可以是单独链接的文档。handoff 用于续接工作，不是另一份 design authority。 diff --git a/dist/claude-code/structured-coding/standards-template.md b/dist/claude-code/structured-coding/standards-template.md index 3629ed5..935288b 100644 --- a/dist/claude-code/structured-coding/standards-template.md +++ b/dist/claude-code/structured-coding/standards-template.md @@ -26,6 +26,17 @@ a trigger off; attempting that is refused, naming the field, rather than quietly ignored. If you genuinely need to skip a team check, that belongs in the PR as a recorded deviation, where a reviewer can see it. +Keeping the personal file out of version control is what makes it personal, so +ignore it along with the planning directory: + +```text +.structured-coding/plans/ +.structured-coding/standards.local.md +``` + +This file, `.structured-coding/standards.md`, is the opposite: it belongs in +version control, because Git tracking it is what makes it the team's standard. + Trust is decided by whether Git tracks the file, never by its name. A tracked file can be edited by any contributor in a pull request; an untracked one can only have been written on your own machine. diff --git a/dist/codex/structured-coding/references/agent-workflow.md b/dist/codex/structured-coding/references/agent-workflow.md index 6e84145..e2b992d 100644 --- a/dist/codex/structured-coding/references/agent-workflow.md +++ b/dist/codex/structured-coding/references/agent-workflow.md @@ -22,7 +22,16 @@ Keep these documents together under `.structured-coding/plans/`, one directory p .structured-coding/plans/infra-exp-p0/handoff.md ``` -That is the default, not a requirement. A project that already keeps planning documents somewhere else should keep them there; what matters is that one location is the authority and that a later session can find it. Commit them if later sessions or teammates need to read them, which is usually the point of writing them down. +That is the default, not a requirement. A project that already keeps planning documents somewhere else should keep them there; what matters is that one location is the authority and that a later session can find it. + +Planning documents are development artifacts and default to staying out of version control, alongside the personal standards overlay: + +```text +.structured-coding/plans/ +.structured-coding/standards.local.md +``` + +The shared standards file is the deliberate exception: `.structured-coding/standards.md` is project configuration, and whether Git tracks it is exactly what makes it the team's standard rather than one developer's, so it belongs in version control. Keeping plans local costs a teammate the ability to read them from a fresh clone, while a later session on the same machine still finds them. Commit them when that tradeoff runs the other way for your project. Do not create additional tracking documents that compete with the primary PR ledger. The contract can be a section of the PR design or a separate linked document. The handoff is a continuation aid, not another design authority. diff --git a/dist/codex/structured-coding/references/agent-workflow.zh-CN.md b/dist/codex/structured-coding/references/agent-workflow.zh-CN.md index 24d142d..4753437 100644 --- a/dist/codex/structured-coding/references/agent-workflow.zh-CN.md +++ b/dist/codex/structured-coding/references/agent-workflow.zh-CN.md @@ -22,7 +22,16 @@ .structured-coding/plans/infra-exp-p0/handoff.md ``` -这是默认做法，不是硬性要求。项目如果已经把规划文档放在别处，就继续放在那儿；真正要紧的是只有一个位置是权威，而且后续 session 找得到它。如果希望后续 session 或队友能读到，就把它们提交进版本库——写下来通常就是为了这个。 +这是默认做法，不是硬性要求。项目如果已经把规划文档放在别处，就继续放在那儿；真正要紧的是只有一个位置是权威，而且后续 session 找得到它。 + +规划文档属于开发产物，默认**不进版本库**，和个人的 standards 覆盖文件一起： + +```text +.structured-coding/plans/ +.structured-coding/standards.local.md +``` + +共享的 standards 文件是刻意的例外：`.structured-coding/standards.md` 是项目配置，而"git 有没有 track 它"恰恰就是它成为团队标准而不是某个人标准的判据，所以它应该进版本库。把 plans 留在本地的代价是队友从全新 clone 里读不到它们，而同一台机器上的后续 session 仍然找得到。如果对你的项目来说这个取舍反过来更合适，就提交它们。 不要创建与 primary PR ledger 争夺权威的额外跟踪文档。contract 可以是 PR design 的一节，也可以是单独链接的文档。handoff 用于续接工作，不是另一份 design authority。 diff --git a/dist/codex/structured-coding/standards-template.md b/dist/codex/structured-coding/standards-template.md index 3629ed5..935288b 100644 --- a/dist/codex/structured-coding/standards-template.md +++ b/dist/codex/structured-coding/standards-template.md @@ -26,6 +26,17 @@ a trigger off; attempting that is refused, naming the field, rather than quietly ignored. If you genuinely need to skip a team check, that belongs in the PR as a recorded deviation, where a reviewer can see it. +Keeping the personal file out of version control is what makes it personal, so +ignore it along with the planning directory: + +```text +.structured-coding/plans/ +.structured-coding/standards.local.md +``` + +This file, `.structured-coding/standards.md`, is the opposite: it belongs in +version control, because Git tracking it is what makes it the team's standard. + Trust is decided by whether Git tracks the file, never by its name. A tracked file can be edited by any contributor in a pull request; an untracked one can only have been written on your own machine. diff --git a/dist/structured-coding-claude-code.zip b/dist/structured-coding-claude-code.zip index 7ac20a9..8b725da 100644 Binary files a/dist/structured-coding-claude-code.zip and b/dist/structured-coding-claude-code.zip differ diff --git a/dist/structured-coding-codex.zip b/dist/structured-coding-codex.zip index 9876509..59f3ac5 100644 Binary files a/dist/structured-coding-codex.zip and b/dist/structured-coding-codex.zip differ diff --git a/structured-coding/references/agent-workflow.md b/structured-coding/references/agent-workflow.md index 6e84145..e2b992d 100644 --- a/structured-coding/references/agent-workflow.md +++ b/structured-coding/references/agent-workflow.md @@ -22,7 +22,16 @@ Keep these documents together under `.structured-coding/plans/`, one directory p .structured-coding/plans/infra-exp-p0/handoff.md ``` -That is the default, not a requirement. A project that already keeps planning documents somewhere else should keep them there; what matters is that one location is the authority and that a later session can find it. Commit them if later sessions or teammates need to read them, which is usually the point of writing them down. +That is the default, not a requirement. A project that already keeps planning documents somewhere else should keep them there; what matters is that one location is the authority and that a later session can find it. + +Planning documents are development artifacts and default to staying out of version control, alongside the personal standards overlay: + +```text +.structured-coding/plans/ +.structured-coding/standards.local.md +``` + +The shared standards file is the deliberate exception: `.structured-coding/standards.md` is project configuration, and whether Git tracks it is exactly what makes it the team's standard rather than one developer's, so it belongs in version control. Keeping plans local costs a teammate the ability to read them from a fresh clone, while a later session on the same machine still finds them. Commit them when that tradeoff runs the other way for your project. Do not create additional tracking documents that compete with the primary PR ledger. The contract can be a section of the PR design or a separate linked document. The handoff is a continuation aid, not another design authority. diff --git a/structured-coding/references/agent-workflow.zh-CN.md b/structured-coding/references/agent-workflow.zh-CN.md index 24d142d..4753437 100644 --- a/structured-coding/references/agent-workflow.zh-CN.md +++ b/structured-coding/references/agent-workflow.zh-CN.md @@ -22,7 +22,16 @@ .structured-coding/plans/infra-exp-p0/handoff.md ``` -这是默认做法，不是硬性要求。项目如果已经把规划文档放在别处，就继续放在那儿；真正要紧的是只有一个位置是权威，而且后续 session 找得到它。如果希望后续 session 或队友能读到，就把它们提交进版本库——写下来通常就是为了这个。 +这是默认做法，不是硬性要求。项目如果已经把规划文档放在别处，就继续放在那儿；真正要紧的是只有一个位置是权威，而且后续 session 找得到它。 + +规划文档属于开发产物，默认**不进版本库**，和个人的 standards 覆盖文件一起： + +```text +.structured-coding/plans/ +.structured-coding/standards.local.md +``` + +共享的 standards 文件是刻意的例外：`.structured-coding/standards.md` 是项目配置，而"git 有没有 track 它"恰恰就是它成为团队标准而不是某个人标准的判据，所以它应该进版本库。把 plans 留在本地的代价是队友从全新 clone 里读不到它们，而同一台机器上的后续 session 仍然找得到。如果对你的项目来说这个取舍反过来更合适，就提交它们。 不要创建与 primary PR ledger 争夺权威的额外跟踪文档。contract 可以是 PR design 的一节，也可以是单独链接的文档。handoff 用于续接工作，不是另一份 design authority。 diff --git a/structured-coding/standards-template.md b/structured-coding/standards-template.md index 3629ed5..935288b 100644 --- a/structured-coding/standards-template.md +++ b/structured-coding/standards-template.md @@ -26,6 +26,17 @@ a trigger off; attempting that is refused, naming the field, rather than quietly ignored. If you genuinely need to skip a team check, that belongs in the PR as a recorded deviation, where a reviewer can see it. +Keeping the personal file out of version control is what makes it personal, so +ignore it along with the planning directory: + +```text +.structured-coding/plans/ +.structured-coding/standards.local.md +``` + +This file, `.structured-coding/standards.md`, is the opposite: it belongs in +version control, because Git tracking it is what makes it the team's standard. + Trust is decided by whether Git tracks the file, never by its name. A tracked file can be edited by any contributor in a pull request; an untracked one can only have been written on your own machine. diff --git a/translations.json b/translations.json index 82818c8..28d269f 100644 --- a/translations.json +++ b/translations.json @@ -28,8 +28,8 @@ { "english": "structured-coding/references/agent-workflow.md", "chinese": "structured-coding/references/agent-workflow.zh-CN.md", - "english_sha256": "b5e34cf75c303c41c57cfe2b4c4b2e34a23e581c0042fa844d5728e0c4e635ef", - "chinese_sha256": "beccae6aaeccce1317508f7d6d05e7baf650cfc51773600d3cefcb40121571d5" + "english_sha256": "17bec8c02873cd71eca246615c7577020be6685fa4b261bedc744c27d5bec5df", + "chinese_sha256": "7169c2467c62db1ec99e94b6ecdd1a46afa1458844bcc81ab16a71c12b07ada0" }, { "english": "structured-coding/references/adaptation.md",